oar

README

OAR — Open ARchive

A modern, verifiable, self-healing archive format with a CLI, a desktop GUI, a headless web UI/REST API, a deduplicating backup repository, and read-only conversion from a dozen foreign formats — all in one pure-Go tool.

coverage 76% · govulncheck clean · pure Go (optional cgo for DMG) · format 1.0

OAR is a from-scratch archive format (.oar) built around three ideas other formats bolt on as afterthoughts:

• Integrity is mandatory, not optional. Every block and every file is BLAKE3-hashed; corruption is detected before you ever see bad bytes.
• Damage is survivable. Built-in Reed-Solomon recovery records let oar repair reconstruct an archive that has lost whole regions to bit rot or a bad sector.
• Security is first-class. Authenticated encryption (AES-256-GCM or XChaCha20-Poly1305) with Argon2id key derivation, key commitment, and digital signatures — Ed25519, post-quantum ML-DSA-65 (FIPS 204), or hybrid — embedded or detached.

On top of the format sits a full toolkit: a deduplicating versioned backup repository (local, S3, Azure Blob, GCS, SMB/CIFS, SFTP, FTP, WebDAV, OpenStack Swift, or an oar serve HTTP endpoint), a compliance layer (append-only/WORM, a tamper-evident audit log, crypto-shredding, and automated restore-verification), a control-plane with an endpoint agent, a FUSE mount, a web console with an OpenAPI REST API, a Wails desktop app, and read-only conversion from ZIP, TAR, gzip/xz/zstd/bzip2/lz4, 7z, RAR, ISO 9660, and DMG.

---

Key features

• Strong compression, automatic codec selection. zstd (levels 1–8), LZMA2/xz (level 9, maximum ratio), LZ4 (--fast), or store. An entropy heuristic skips already-compressed data, and a grow guard guarantees a block never gets bigger.
• Content-aware filters. BCJ branch-call converters for x86 / ARM64 / ARM / Thumb / RISC-V / BCJ2, plus delta filters for sampled data (audio, pixels, tables). Auto-detected from executable headers.
• Random access, solid compression, or streaming. A footer index gives O(1) per-file extraction; small files are batched into solid blocks for ratio; --stream writes forward-only to a pipe or tape with no temp staging.
• Authenticated encryption. AES-256-GCM (default) or XChaCha20-Poly1305, Argon2id KDF (per-archive parameters), key commitment for fast and unambiguous wrong-password detection, deterministic per-block nonces.
• Digital signatures. Ed25519, post-quantum ML-DSA-65 (FIPS 204), or a hybrid of both; embedded in-place or as a countersignable .sig sidecar; always verified when present, optionally required (--require-signature, --pub).
• Self-healing. Reed-Solomon parity (--recovery N), self-locating recovery section with replicated headers; oar scrub reports your damage budget, oar repair reconstructs.
• Standalone protection for any file. oar protect / oar heal write a PAR2-style .oarp sidecar that protects and repairs any file, not just .oar.
• Deduplicating backup repository. FastCDC content-defined chunking, cross-snapshot dedup, encrypted chunk store (keyed-BLAKE3 chunk IDs), retention policies, and lock-free concurrent backups with two-phase fossil-collection prune.
• Remote backends. Local directory, s3://, azblob://, gs://, smb://, sftp://, ftp://, dav(s)://, swift://, or http(s):// to an oar serve daemon. SFTP uses strict known-hosts with TOFU pinning.
• Compliance & operations. Append-only repositories and storage-enforced WORM (S3 Object Lock), a tamper-evident hash-chained audit log, crypto-shredding for GDPR-style erasure, automated restore-verification, and a managed keyring (rotate the passphrase without re-encrypting; X25519 recovery recipients for escrow). An oar server control-plane adds a scheduler, Prometheus metrics, alerts, a dashboard, and an endpoint backup agent.
• Foreign-format conversion (read-only). Convert/extract/list/verify ZIP (incl. AES & ZipCrypto), TAR, gzip/xz/zstd/bzip2/lz4, 7z, RAR (v4/v5), ISO 9660 (Rock Ridge/Joliet), and DMG (HFS+, with -tags dmg).
• Three front-ends. A Cobra/Fang CLI, a self-contained web console (oar web) with a built-in Swagger UI, and a Wails 3 + Svelte desktop GUI.
• FUSE mount. Browse an archive or a repository snapshot read-only as a normal filesystem (Linux/macOS).
• Reproducible output. --reproducible zeroes timestamps/owners; ordered-parallel emission makes output byte-identical regardless of worker count.

---

Install

go install

go install github.com/khovanskiy5/oar/cmd/oar@latest

Build from source

git clone https://github.com/khovanskiy5/oar
cd oar
make build          # pure-Go CLI → bin/oar
make install        # symlink bin/oar into /usr/local/bin (override with INSTALL_DIR=)

DMG support (optional, needs cgo)

Reading Apple DMG images needs LZFSE via cgo and a C compiler:

make build-dmg      # CGO_ENABLED=1, -tags dmg → bin/oar +dmg

The default build is pure Go and fully cross-compilable; only DMG reading requires cgo.

Desktop GUI

make gui            # Wails 3 + Svelte app bundle (needs wails3 + Bun)

---

Quickstart

Create, extract, verify

oar create backup.oar ~/Documents ~/Pictures        # solid archive
oar list backup.oar                                 # browse contents
oar extract backup.oar ./restore                    # extract everything
oar verify backup.oar                               # full BLAKE3 verification

Tune compression and resilience:

oar create max.oar ./src --level 9 --recovery 10    # LZMA2 + 10% parity
oar create fast.oar ./logs --fast                   # LZ4, small blocks, low latency
oar create -                ./src > out.oar          # write archive to stdout
oar create pipe.oar ./src --stream                  # forward-only (pipe/tape)

Encryption

oar create secret.oar ./private --password -                       # read password from stdin
OAR_PASSWORD=hunter2 oar create secret.oar ./private               # from environment
oar create secret.oar ./private --password - --cipher chacha       # XChaCha20-Poly1305
oar extract secret.oar ./out --password -

Signing

oar keygen -o mykey                                  # → mykey.key, prints public key hex
oar sign backup.oar --key mykey.key                  # embed an Ed25519 signature
oar verify-sig backup.oar --pub <hex>                # verify against an expected signer
oar sign backup.oar --key mykey.key --detached       # → backup.oar.sig (countersignable)

Require a valid signature at read time:

oar extract backup.oar ./out --require-signature --pub <hex>

Backup repository

oar snapshot ./repo ~/Documents -m "nightly"         # incremental, deduplicated snapshot
oar snapshots ./repo                                  # list snapshots (newest first)
oar restore ./repo latest ./restore                   # restore the most recent snapshot
oar forget ./repo --keep-daily 7 --keep-weekly 4 --prune
oar prune ./repo                                       # reclaim unreferenced chunks

Remote and networked repositories:

oar snapshot s3://endpoint/bucket/prefix ~/data       # S3/B2/R2/MinIO/Wasabi
oar serve ./repo --addr :8462 --token secret          # expose a repo over HTTP
oar snapshot http://host:8462 ~/data                  # back up to the served repo

Web UI / REST API

oar web --addr :8463 --token secret                   # http://localhost:8463/?token=secret
oar web --detach                                       # daemonize, print PID + URL

The console serves a self-contained UI plus an OpenAPI 3.1 spec at /api/openapi.json and an offline Swagger UI at /api/docs. Example call:

curl -s -X POST http://localhost:8463/api/list \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -d '{"path":"backup.oar"}'

Desktop GUI

make gui            # build the Wails app, then launch the produced bundle

The GUI mirrors the CLI (create / open / convert / sign / snapshots / protect), supports drag-and-drop, FUSE mount, and an embedded web console toggle.

Mount (FUSE)

oar mount backup.oar /mnt/oar                         # mount an archive read-only
oar mount ./repo latest /mnt/snap                     # mount a repository snapshot

Needs libfuse (Linux) or macFUSE (macOS).

Foreign formats (interop)

oar convert photos.zip photos.oar                     # ZIP → OAR
oar convert image.iso image.oar                       # ISO 9660 → OAR
oar convert disk.dmg disk.oar                         # DMG → OAR (needs -tags dmg)
oar list archive.7z                                    # list a foreign archive
oar verify backup.tar.zst                              # integrity-test a foreign archive
oar extract data.rar ./out                             # extract a RAR v4/v5

OAR reads ZIP, TAR, gzip/xz/zstd/bzip2/lz4, 7z, RAR, ISO, and DMG. It is read-only for foreign formats — OAR never writes them.

Protect & heal any file

oar protect bigfile.mkv --percent 10                  # → bigfile.mkv.oarp
oar heal bigfile.mkv --verify                         # check against the sidecar
oar heal bigfile.mkv                                   # repair in place if damaged

---

Feature matrix highlight

Capability	OAR
Per-block + per-file hash	BLAKE3 (mandatory)
Error correction	Reed-Solomon parity, configurable %
Encryption	AES-256-GCM / XChaCha20-Poly1305, Argon2id
Signatures	Ed25519, embedded or detached sidecar
Random access	Footer index (O(1) per-file extract)
Solid compression	Yes (extension-clustered solid blocks)
Streaming write	Yes (--stream, no temp staging)
Deduplicating backups	FastCDC repository, cross-snapshot dedup
Remote storage	S3, SFTP, FTP, WebDAV, HTTP daemon
Mount as filesystem	FUSE (Linux/macOS)
Read foreign formats	ZIP, TAR, gz/xz/zst/bz2/lz4, 7z, RAR, ISO, DMG
Reproducible output	Yes (--reproducible, deterministic)

---

Documentation

• English: docs/en/index.md — Getting Started · CLI Reference · Configuration
• Русский: docs/ru/index.md — Начало работы · Справочник CLI · Конфигурация

---

Building & testing

make build          # build the CLI (pure Go)
make test           # tests with the race detector
make cover          # coverage report → coverage.html (~76%)
make vet lint       # static analysis
make vuln           # govulncheck
make fuzz           # run every fuzz target
make cross-check    # compile-check linux/darwin/windows

OAR is pure Go and cross-compiles to linux, darwin, and windows (amd64/arm64). Only optional DMG reading needs cgo.

---

License

OAR is dual-licensed:

• Open source: GNU AGPL-3.0 — free to use, modify, and distribute; if you distribute a modified version or run it as a network service, you must release your corresponding source under the AGPL.
• Commercial license — for embedding OAR in closed-source products or running a proprietary SaaS without the AGPL's source-disclosure obligation. See COMMERCIAL.md or contact dev2.khovanskiy@gmail.com.

Contributions are accepted under the Contributor License Agreement so the project can keep offering both licenses; see CONTRIBUTING.md. Third-party attributions are in NOTICE. To report a vulnerability, see SECURITY.md.