ShadowBit — one encrypted file, one password, no accounts

Capabilities

Everything you need.

AES-256-GCM or ChaCha20-Poly1305. scrypt key derivation. An authenticated header that rejects tampering. Keyfile second factors. A one-time recovery key. Paranoid mode. A complete security stack with zero dependencies beyond Node.js built-ins for the cryptographic core.

Why ShadowBit?

Encryption that travels with you.

ShadowBit turns any collection of files into a single encrypted container you can email, carry on a USB drive, or share anywhere. No cloud, no account, no subscription. The vault is just a file.

Unlike zip encryption (weak and crackable), cloud-only vaults (require trust in a provider), or full-disk tools (not portable), ShadowBit gives you one file that travels anywhere and opens on any computer that has ShadowBit installed.

Workflow

Four steps, every time.

The same simple loop — whether you're using the CLI or the desktop app.

Installation

Get up and running.

Choose your platform. Requires Node.js 20+.

Recipes

Common workflows.

Share a vault

# Create — you will be prompted for a password
./shadow-bit create shared --no-recovery
./shadow-bit open shared
cp report.pdf <working-folder>/
./shadow-bit close shared

# Send shared.svlt via email/USB
# Recipient opens with the same password

Recover a forgotten password

# Use the recovery key printed at creation
./shadow-bit recover project
# Recovery key: A7KX9-MP2VQ-8NW4T-…
# New password: ********
# ✓ Password reset via recovery key.

Automate with scripts

# Set the password once, out of band.
# Prefer the env var over --password: the flag is
# visible to other users via `ps` and lands in
# your shell history.
export SHADOWBIT_PASSWORD="$VAULT_PASS"

./shadow-bit create backup --no-recovery
./shadow-bit open backup
rsync -av ~/Documents/ <working-folder>/
./shadow-bit close backup

Migrate an existing folder

# One command seeds from a folder
./shadow-bit create secrets \
  --seed ~/Documents/secrets

# Verify contents
./shadow-bit open secrets
ls <working-folder>
./shadow-bit discard secrets

Q&A

Questions, answered.

How-to recipes for the features you can actually use, plus a plain account of what ShadowBit does not do. If a guarantee is not listed here, it does not exist.

CLI Reference

Every command, documented.

Run via ./shadow-bit or node dist/cli/index.js. Every command that needs a password prompts for it invisibly by default — pass SHADOWBIT_PASSWORD to automate. --password still works but is deprecated: it exposes the password to other users through ps and to your shell history.

Desktop App

A native GUI for every platform.

The Electron app shares the same cryptographic core as the CLI. Four tabs cover every workflow — no terminal required.

$ npm run gui # build + launch Electron

$ npm run gui:dev # launch without rebuilding

Security Model

Designed for real-world threats.

An internal code review was completed and its findings fixed, each with a regression test. That is a self-review, not an independent security audit — nobody outside the project has assessed this code.

🔍

Independently reviewed — and not professionally audited

ShadowBit has been through an internal code review whose findings are fixed and covered by an automated suite of 232 tests (crypto round-trips, the full keyfile lifecycle, the real CLI as a subprocess, the real desktop app, WCAG 2.2 AA, responsive reflow, and performance budgets). That is a self-review, not an independent security audit — read SECURITY.md and SECURITY_AUDIT.md in the repository for the full report and the threat model.

⚠️

Secure erase is best-effort. On SSDs, APFS, and copy-on-write filesystems, wear-leveling and snapshots may retain old data. For hard guarantees, rely on full-disk encryption (FileVault, BitLocker, LUKS) in addition to the vault's own shred.

What is a Vault?

One file holds everything.

A .svlt file is a self-contained encrypted archive. It carries everything needed to decrypt it — KDF parameters, salt, wrapped master key, auth tag — except your password. Email it, put it on USB, attach it to a message. The recipient opens it with ShadowBit and the password you share out-of-band.

📄 project.svlt

HEADER (plaintext)

magic + version KDF params + salt password-wrapped key recovery-wrapped key IV + GCM auth tag cipher · keyfileRequired headerMac (HMAC-SHA256)

envelope encryption boundary

PAYLOAD (ciphertext)

AES-256-GCM or ChaCha20-Poly1305( deflate( your files ) )

Envelope Encryption

A random 256-bit MEK encrypts your files. The MEK is wrapped by your password-derived key. Changing the password only re-wraps the MEK — instant.

Authenticated Encryption

AES-256-GCM or ChaCha20-Poly1305 with a fresh random IV. Wrong passwords and tampering are detected as decryption failures.

Authenticated Header

The entire header is protected by an HMAC-SHA256 (HKDF-derived from the MEK). Header tampering — inducing fake KDF params or recovery keys — is detected and rejected on open.

Recovery Key

An optional second independent wrapping of the MEK. A forgotten password isn't permanent lockout.

Architecture

Clean, layered design.

The cryptographic core is UI-agnostic. The CLI and Electron GUI are thin frontends over the same engine.