larzvault

An encrypted secrets manager in pure Python.

Keep your API keys, tokens, and connection strings in one file, encrypted under a master passphrase — instead of scattered across plaintext .env files, shell history, and screenshots. Open the vault with the passphrase, read your secrets, inject them into the environment. Done.

from larzvault import Vault

v = Vault.create("secrets.vault", "master passphrase")
v.set("STRIPE_KEY", "sk_live_...")
signing = v.generate("SIGNING_KEY")        # strong random secret, stored + returned
v.save()

# later, elsewhere
v = Vault.open("secrets.vault", "master passphrase")
v.get("STRIPE_KEY")
v.to_env()                                 # every secret into os.environ

Why

• Real authenticated encryption. The master key is derived from your passphrase with scrypt (memory-hard, so brute-forcing is expensive) and the secrets are sealed with ChaCha20-Poly1305. A wrong passphrase or a single tampered byte raises WrongPassphrase — it never returns garbage or silently weakens itself.
• The KDF settings are authenticated too. An attacker can't edit the file to downgrade the scrypt cost — the parameters are covered by the AEAD tag.
• One portable file. Commit it to a private repo, drop it on a server, back it up — it's useless without the passphrase.
• Drop-in env injection. to_env() loads secrets straight into os.environ, so existing os.environ["STRIPE_KEY"] code just works.
• Rotation built in. generate() makes strong secrets; change_passphrase() re-keys the vault with a fresh salt.

Install

pip install larzvault

Built on larzcrypt (itself pure Python, zero third-party dependencies) for the cryptography.

Usage

from larzvault import Vault, WrongPassphrase

# create
v = Vault.create("app.vault", "hunter2")
v.set("DB_URL", "postgres://user:pass@host/db")
v.set("FLAGS", {"beta": True})            # any JSON-serializable value
v.save()

# open (raises WrongPassphrase on a bad passphrase or tampered file)
try:
    v = Vault.open("app.vault", "hunter2")
except WrongPassphrase:
    ...

v.get("DB_URL")
v.keys()                                   # ["DB_URL", "FLAGS"]
v.delete("FLAGS")
v.generate("API_KEY")                      # random, returned + stored
v.to_env(prefix="APP_")                    # os.environ["APP_DB_URL"] = ...
v.change_passphrase("new-stronger-one")    # re-key + save
v.save()

Threat model (read this)

larzvault protects secrets at rest: someone who copies your vault file learns nothing without the passphrase, and can't tamper with it undetected. It does not protect against a compromised running process (once you open the vault or call to_env(), the secrets are in memory/os.environ like any app), a keylogged passphrase, or swap/core-dump leakage. Choose a strong passphrase — the scrypt cost slows guessing, but a weak passphrase is still a weak passphrase.

Tests

python -m unittest discover -s tests -v      # 14 tests incl. tamper + downgrade detection

The Larz stack

Pure-Python, zero-third-party-dependency building blocks:

• larz — money-native web framework
• larzchain — from-scratch PoW blockchain
• larzmoney — exact, penny-perfect money
• larzcrypt — pure-Python cryptography toolkit
• larzdb — crash-safe embedded database
• larzagent — zero-dep AI agent framework
• larzchart — data to inline SVG charts
• larzmark — Markdown + SEO static sites
• larztask — durable background job queue
• larzvault — this library

License

MIT © larz-scripter