Ethernity

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

Table of Contents

Start here: Quick Start

• What Is Ethernity?
• Status (Stable v1)
• 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

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.

Status (Stable v1)

• Until a v1.0.0 release is published on GitHub Releases, Ethernity remains experimental.
• Once v1.0.0 is released, stable v1 backups and recovery artifacts follow the baseline in docs/format.md.
• From v1.0.0 onward, future stable releases will maintain backward compatibility for stable v1 backups and recovery artifacts.
• Do not use Ethernity as your only backup path; run recovery drills and keep an independent backup.

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.

Prerequisites

• Python 3.13+ (for source and pip-based installs)
• cosign only if you verify release artifacts
• Chromium binaries for PDF rendering (auto-installed on first backup/render run)
• local disk space for generated PDFs and optional shard documents

1) Install from Release Artifacts (Recommended)

Download the archive matching your OS and CPU.

Artifact naming:

ethernity-{tag}-{os}-{arch}.{zip|tar.gz}

Download and verify on Linux:

TAG="v0.9.1"
OS_ARCH="linux-x64" # or linux-arm64
BASE="ethernity-${TAG}-${OS_ARCH}.tar.gz"

curl -LO "https://github.com/MinorGlitch/ethernity/releases/download/${TAG}/${BASE}"
curl -LO "https://github.com/MinorGlitch/ethernity/releases/download/${TAG}/${BASE}.sigstore.json"

cosign verify-blob --bundle "${BASE}.sigstore.json" "${BASE}"

tar -xzf "${BASE}"
./ethernity-${TAG}-${OS_ARCH}/ethernity --help

Download and verify on macOS:

TAG="v0.9.1"
OS_ARCH="macos-arm64" # or macos-x64
BASE="ethernity-${TAG}-${OS_ARCH}.tar.gz"

curl -LO "https://github.com/MinorGlitch/ethernity/releases/download/${TAG}/${BASE}"
curl -LO "https://github.com/MinorGlitch/ethernity/releases/download/${TAG}/${BASE}.sigstore.json"

cosign verify-blob --bundle "${BASE}.sigstore.json" "${BASE}"

tar -xzf "${BASE}"
./ethernity-${TAG}-${OS_ARCH}/ethernity --help

Windows PowerShell equivalent:

$Tag = "v0.9.1"
$OsArch = "windows-x64" # currently published Windows variant
$Base = "ethernity-$Tag-$OsArch.zip"

Invoke-WebRequest "https://github.com/MinorGlitch/ethernity/releases/download/$Tag/$Base" -OutFile $Base
Invoke-WebRequest "https://github.com/MinorGlitch/ethernity/releases/download/$Tag/$Base.sigstore.json" -OutFile "$Base.sigstore.json"

cosign verify-blob --bundle "$Base.sigstore.json" "$Base"

Expand-Archive -Path $Base -DestinationPath .
.\ethernity-$Tag-$OsArch\ethernity.exe --help

For full verification and provenance guidance, use Wiki: Release Artifacts.

2) Install via pipx or pip

pipx is recommended when you want isolated CLI installation:

pipx install ethernity-paper
ethernity --help

pip is acceptable inside an existing Python environment:

pip install ethernity-paper
ethernity --help

3) 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_*.pdf (optional)	threshold shard artifacts when sharding enabled
signing_key_shard_*.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
cmp ./vault-export.json ./vault-export.recovered.json

Expected result: cmp exits with status 0 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 pytest tests/unit tests/integration -q
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
cd kit
npm ci
# Requires libdeflate-gzip (for example: apt install libdeflate-tools)
node build_kit.mjs
cd ..

This rebuild emits both recovery kit variants:

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

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

Contributing

Contributions are welcome. 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. Also worth checking out:

• Rememory by eljojo

Core open-source building blocks include:

• age
• Typer, Rich, and Questionary
• fpdf2, Jinja2, and Playwright

Standards and verification ecosystem acknowledgements:

• BIP-39 mnemonic standard
• Sigstore and Cosign for artifact verification workflows

Star History

License

GPLv3 or later. See LICENSE for full terms.

(back to top)