Ethernity

Secure, offline-recoverable backups with printable QR documents and a browser recovery kit.
Format spec · Format notes · Format changes · Security policy
Issues · Report Bug · Request Feature

Table of Contents

• Status
• What Is Ethernity?
• What Ethernity Supports
• How Much Data Can I Store? (Quick Guide)
• Who It's For / Not For
• Document Previews
• Quick Start
• First Backup
• First Recovery
• Troubleshooting (Quick Fixes)
• Workflow Playbooks
• Security at a Glance
• How Recovery Inputs Work
• Command Cheatsheet
• Release Artifacts
• Development Quickstart
• Contributing
• Credits
• Star History
• License

Status

• Good news: Ethernity is now stable.
• Backups and recovery artifacts follow the baseline in docs/format.md.
• Future stable releases guarantee backward compatibility for existing backups and recovery artifacts.
• Please still treat Ethernity as one layer in your strategy: run recovery drills and keep an independent backup.

What Is Ethernity?

Ethernity is a Python CLI that turns sensitive files into encrypted, printable recovery artifacts. The output combines machine-readable QR payloads with human-readable fallback text, so you can recover data offline even if scanning fails.

A bundled browser recovery kit can reconstruct and decrypt backups locally, without calling cloud services or online APIs. This is designed for high-friction, low-dependency recovery scenarios where physical media matters.

Ethernity is opinionated around verifiability: formats are documented, payload structures are explicit, and release artifacts include provenance material.

What Ethernity Supports

Core capabilities you can rely on today:

• Backup workflows
  • encrypt single files or directory inputs into recovery artifacts
  • produce printable QR and recovery documents for offline custody
  • support manifest payload codecs raw and gzip
  • optional passphrase sharding with configurable threshold/quorum
  • optional signing-key sharding with independent threshold/quorum controls
• Recovery workflows
  • recover from scanned artifacts (--scan supports image, PDF, or directory sources)
  • recover from fallback text (--fallback-file) when scan quality is poor
  • recover from exported QR payload text (--payloads-file)
  • decode QR transport payloads in raw bytes (binary) or unpadded base64 mode
  • include shard/auth inputs via fallback text files, payload files, or shard directories
• Recovery kit workflows
  • generate recovery-kit PDF output from the CLI (ethernity kit)
  • use bundled browser recovery kits (lean and scanner variants) for local reconstruction/decryption
• Operational controls
  • supported template designs (archive, forge, ledger, maritime, sentinel)
  • A4/Letter paper targeting and deterministic render layout
  • documented format baseline and release-provenance verification guidance

How Much Data Can I Store? (Quick Guide)

Most templates use a 3x4 first-page grid (11 MAIN + 1 AUTH). One-page only: this section describes first-page fit, not total backup capacity.

Baseline one-page capacity at defaults (error = M, QR transport raw):

Preferred chunk size	One-page baseline capacity (incompressible profile)
768 B	8,063 B (7.87 KiB)
1,536 B	16,510 B (16.12 KiB)

Advanced combinations with fixed QR version (version = 33, auto-scaling disabled):

This comparison isolates raw vs base64 QR transport impact with QR error correction M. All rows below use payload codec gzip.

Preferred chunk size	QR transport codec	Max original input (incompressible profile)	Max original input (moderately compressible JSON-like profile)
768 B	raw	8,020 B (7.83 KiB)	73,624 B (71.90 KiB)
768 B	base64	8,020 B (7.83 KiB)	73,624 B (71.90 KiB)
1,536 B	raw	16,462 B (16.08 KiB)	152,798 B (149.22 KiB)
1,536 B	base64	12,783 B (12.48 KiB)	118,198 B (115.43 KiB)

If you raise QR error correction to Q or H, one-page capacity drops further. The JSON-like profile is a practical middle ground; highly repetitive synthetic text can compress much more, while incompressible binary data compresses little or not at all.

Who It's For / Not For

Ethernity is a good fit if you need:

• offline-capable secret recovery workflows
• printable artifacts for long-term or distributed physical custody
• threshold-shared recovery for multi-party control
• auditable data handling steps instead of black-box cloud backup behavior

Ethernity is usually not a good fit if you need:

• always-on background synchronization
• turnkey, no-maintenance backup infrastructure
• centralized managed recovery operated by a third-party service

Document Previews

Rendered examples from the Sentinel design on A4 paper. These are first-page previews of the generated PDFs.

Classic template previews (Maritime):

Quick Start

Fastest path: install, run one backup, run one recovery, then confirm outputs match.

1) macOS and Linux

Homebrew works on both macOS and Linux and is the easiest place to start:

brew tap minorglitch/tap
brew install ethernity
ethernity --help

If you prefer a Python-managed install, pipx also works on both macOS and Linux:

pipx install ethernity-paper
ethernity --help

2) Windows

Use the PowerShell installer. It resolves the latest Windows release, downloads it, installs it into your user profile, and updates your user PATH.

$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://raw.githubusercontent.com/MinorGlitch/ethernity/master/install.ps1" -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1
ethernity --help

For manual signed artifact downloads and verification, use Wiki: Release Artifacts.

3) Alternative: Install via pip

Use this when you want Ethernity inside an existing Python environment.

pip is acceptable inside an existing Python environment:

pip install ethernity-paper
ethernity --help

4) Install from Source (Development or Audit)

git clone https://github.com/MinorGlitch/ethernity.git
cd ethernity
uv sync --extra dev --extra build
uv run ethernity --help

First Backup

Create a backup:

ethernity backup --input ./secrets.txt --output-dir ./backup-demo

Common outputs:

File	Purpose
qr_document.pdf	primary scan source for payload recovery
recovery_document.pdf	fallback text and metadata recovery path
shard-*-N-of-K.pdf (optional)	threshold shard artifacts when sharding enabled
signing-key-shard-*-N-of-K.pdf (optional)	separate signing-key shard artifacts

First Recovery

Recover from scans:

ethernity recover --scan ./backup-demo --output ./restored.bin

For fallback-text and shard-driven recovery paths, use playbooks C and D below.

Generate Recovery Kit

ethernity kit --output ./recovery_kit_qr.pdf

Quick End-to-End Verification

# 1) Create sample input
printf '{"vault":"demo"}\n' > vault-export.json

# 2) Backup
ethernity backup --input ./vault-export.json --output-dir ./demo-backup

# 3) Recover from scans
ethernity recover --scan ./demo-backup --output ./vault-export.recovered.json

# 4) Validate payload equality (macOS/Linux)
cmp ./vault-export.json ./vault-export.recovered.json

# 4) Validate payload equality (Windows PowerShell)
fc.exe /b .\vault-export.json .\vault-export.recovered.json

Expected result: cmp (or fc /b) reports no differences and recovered JSON is byte-identical.

Troubleshooting (Quick Fixes)

Use the wiki troubleshooting guide for onboarding and recovery issues:

• Wiki: Troubleshooting

For release verification and artifact provenance details, use:

• Wiki: Release Artifacts

Workflow Playbooks

Runbook templates and operator checklists now live in the wiki:

• Wiki: Backup Workflow
• Wiki: Recovery Workflow

Use the README Quick Start above for the shortest install/backup/recovery path, then adopt a wiki playbook for your actual operating procedure.

Security at a Glance

Ethernity helps protect against:

• data loss in low-connectivity or offline-only scenarios
• accidental corruption through frame-level validation and integrity checks
• single-holder compromise when threshold sharding is used correctly

Ethernity does not protect against:

• compromised endpoints at backup or recovery time
• weak, reused, or leaked passphrases
• policy failures in shard custody distribution
• operational mistakes that skip recovery drills

Hard warning:

• do not treat generated artifacts as magically safe by default
• security outcome depends on custody controls, passphrase quality, and tested runbooks

Read full policy and reporting guidance in SECURITY.md.

For format-level guarantees and bounds, use:

• docs/format.md
• docs/format_notes.md

How Recovery Inputs Work

Data-flow diagrams, input-mode guidance, and recovery path selection tips now live in the wiki:

• Wiki: Backup Workflow
• Wiki: Recovery Workflow

Command Cheatsheet

Detailed command tables, config examples, and operator defaults moved to:

• Wiki: Command Cheatsheet

Quick references:

• ethernity --help
• ethernity backup --help
• ethernity recover --help
• ethernity kit --help

Release Artifacts

Release packaging, verification, and provenance guidance is maintained in the wiki: Wiki: Release Artifacts.

Development Quickstart

git clone https://github.com/MinorGlitch/ethernity.git
cd ethernity
uv sync --extra dev --extra build
uv run playwright install chromium

Core checks:

uv run pre-commit run --all-files
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run pyright
uv run check-jsonschema --check-metaschema docs/cli_api.schema.json
uv run typos .
uv run pytest tests/unit tests/integration -q
cd kit
npm ci
npm run lint
npm run format:check
npm test
# Requires libdeflate-gzip (for example: apt install libdeflate-tools)
node build_kit.mjs
cd ..

This rebuild emits both recovery kit variants:

• src/ethernity/resources/kit/recovery_kit.bundle.html (lean, default)
• src/ethernity/resources/kit/recovery_kit.scanner.bundle.html (jsQR scanner variant)

Use CONTRIBUTING.md for workflow policy, expectations, and quality gates.

Contributing

Contributions are welcome via fork + pull request. Prefer focused PRs with tests/docs updates when behavior changes.

Before opening a PR, read CONTRIBUTING.md, SECURITY.md, and AGENTS.md.

Credits

Ethernity was heavily inspired by Paperback by cyphar.

Worth checking out:

• Rememory by eljojo

Core open-source building blocks include:

• age via pyrage, plus PyCryptodome and cbor2
• Typer, Rich, and Questionary
• fpdf2, Jinja2, and Playwright
• Segno, zxing-cpp, jsQR, @noble/ciphers, and @noble/hashes

Standards and verification ecosystem acknowledgements:

• age v1 format, BIP-39, RFC 8949 (CBOR), Unicode TR15, z-base-32 reference, and Shamir's secret sharing paper (1979)
• Sigstore and Cosign for artifact verification workflows

Star History

License

GPLv3 or later. See LICENSE for full terms.

(back to top)