UnENVerse

UnENVerse is a local-first secrets manager: the desktop app, unv CLI, and optional server share a SQLCipher-backed vault. This guide describes public, shipping behaviour. It intentionally excludes development handoffs, private paths, and operational notes.

Start with the security model, then use the CLI guide or browse the roadmap.

Security model

The vault is encrypted at rest with SQLCipher. A master password is processed locally with Argon2id; the derived key is not written to disk and is cleared when the vault is locked. The database salt is required to recover a vault, so backups must keep it with the encrypted database.

unv defaults to redacted output. Commands that would expose stored values on stdout require an explicit reveal option; use file output or unv exec when a consumer needs a real secret. The optional server supports TLS pinning, scoped users, and compare-and-swap writes to avoid silent overwrite conflicts.

No security control removes the need to protect an unlocked desktop session or the machine on which it runs. Report vulnerabilities through the repository's security policy.

CLI guide

Use unv describe --json to obtain the machine-readable command contract for the installed version. The common workflow is:

unv status
unv entry add GitHub --type password --username alice --key-stdin
unv get GitHub --field api_key --reveal --out token.txt
unv doctor

Use stdin for secret input where possible. Avoid --reveal on interactive shells, transcripts, or CI logs. unv backup archive creates a recoverable backup containing the vault database and its salt.

The CLI can connect to a remote vault only after a certificate pin is recorded; this prevents a self-signed or local server from becoming an unauthenticated trust exception.

Bundles

A bundle is one card for several entries that belong together (a service's password, its web session and its API app). Members stay ordinary entries.

unv bundle new "Discord bot" --member bot=DiscordBot --member web=DiscordWeb
unv bundle new "Discord bot" --import config.py     # a Python config module, read as data
unv bundle add "Discord bot" Spotify --slot api
unv bundle remove "Discord bot" api                 # detach; the entry is kept
unv bundle dissolve "Discord bot"                   # members return to the grid
unv bundle delete "Discord bot" --yes               # deletes the members too
unv get bundle:Spotify/api --field ID               # the bundle: selector

References use the same selector: ${bundle:Spotify}, ${bundle:Spotify/api}, ${bundle:Spotify/api/ID} and ${bundle:Spotify/prefix} for a bundle-local variable. An ambiguous bundle name resolves to nothing rather than to a guess.

--import never executes the file. It reads string and f-string literals, numbers, booleans and None; anything else is kept as source text with a warning that names the line. A name assigned twice keeps the first value and imports the second as name_2, and later f-strings are rewritten to match.

Files a tool reads

unv emit Npm                       # lists the formats this entry's type offers
unv emit Npm --as npmrc --out ~/.npmrc
unv emit Prod-DB --as dsn --out db.env
unv emit Home-WiFi --as wifi-uri --reveal

emit writes the credential, so it follows export: refused to stdout without --reveal, and written 0600 with --out. Formats: npmrc, pypirc, cargo-credentials, docker-config, netrc (registry tokens); dsn, libpq, jdbc (databases); wifi-uri (Wi-Fi).

Web sessions

unv cookie import capture.txt                       # preview, writes nothing
unv cookie import capture.txt --entry Site --create
unv cookie import export.har --origin https://www.example.com --entry Site
unv cookie import cookies.sqlite --from firefox --host example.com --entry Site

Accepts DevTools Copy as cURL (bash, cmd or PowerShell), HAR, Set-Cookie lines and a Firefox profile's cookies.sqlite. Only the chosen origin's cookies and headers are kept; an Authorization header and other hosts' cookies are dropped and listed by name, never by value. Chrome is refused by name: its cookies are not readable from outside the browser.

OAuth and recovery codes

unv oauth refresh Slack            # ONLINE: sends the refresh token to its token_url
unv codes status GitHub-codes
unv codes next GitHub-codes --reveal   # reading does not spend a code
unv codes use GitHub-codes             # mark the next one used

oauth refresh stores a rotated refresh token in the vault before it reports anything, because the issuer has already invalidated the old one.

Roadmap

Phases 1–23 established encrypted storage, desktop and CLI clients, sharing, accessibility, stored authenticators, and a richer credential model. Phase 24 focuses on shipped-feature reliability, CI hygiene, and this public guide.

The next planned work is composite and bundled secrets, a more legible secrets grid, calendar feeds, an opt-in unique-ID registry, a larger credential type registry, and one row-per-entry storage migration. Later milestones cover behavioural audits, UI/CLI parity, redaction tooling, config validation, nodes, history, approvals, integrations, a provider catalogue, and an authorised pre-1.0 security assessment.

Roadmap ordering may change as defects are found. Compatibility and security work takes priority over feature expansion.

Phase 21: reference correctness

Reference aliases now resolve identity fields such as ID consistently in the desktop app and CLI. Metadata fields are rejected from rendered configuration references, preventing an entry UUID from being silently substituted where a credential value was expected.

Phase 22: stored authenticators

An entry can hold a third-party authenticator seed alongside its credential and produce a live code in the desktop app or CLI. Seeds are redacted stored values; the short-lived derived code is intentionally copyable. URI parsing accepts common otpauth:// exports and preserves non-default algorithm, digits, and period settings.

Phase 23: credential shape

Credentials can name the role of their primary value, include a label and version-aware environment-variable name, represent cookie and user-agent secrets, and choose a copy profile. These changes make exported configuration more precise without replacing the underlying encrypted vault format.

Phase 24: reliability and delivery

Phase 24 fixes defects in previously shipped behaviour: remote authenticator codes, desktop exports, form generation, credential-card grouping, sidebar layout, and forward-compatible edits. CI adds dependency auditing, CodeQL, Dependabot, and immutable action pins. This guide is built with mdBook and published alongside the TypeScript and Rust API references.

Sub-phases

24.1 Bundles and composites. A composite is one value with named secret parts; a bundle is one card over several entries plus its own typed variables, addressed as ${bundle:Name/slot/field}. Python config modules import as bundle variables and export back with templates as f-strings.
24.2 The secrets grid. Type chips, pools as one card, a health scan that names type, field and state.
24.3 Calendar feeds. A revocable, token-addressed .ics URL served by unv-server; it never carries a value, and a locked server answers 503 rather than an empty calendar.
24.4 Unique-ID registry. Keyed hashes only, token-bucket rate limits that count per value (--uid-rate to override), chunked pruning.
24.5 Credential model. A type registry, web-session capture import, files emitted for the tools that read them, OAuth refresh with store-first ordering, and BIP39 checksum validation against the bundled wordlist.

Decision records

Decision records preserve a small number of durable public architectural choices. They are append-only: a changed decision gets a new record that names the record it supersedes.

ADR-0001: Local-first storage

Status: accepted

Keyboard shortcuts

UnENVerse Guide