Project Architecture
This document describes how HeelonVault works internally: code layout, startup, key model and runtime security guarantees. It is written for security reviewers, administrators and contributors. To install or use the application, see QUICKSTART.md and USER_GUIDE.en.md.
Overview
Section titled “Overview”HeelonVault is a local-first desktop application written in Rust:
- UI: GTK4 + libadwaita;
- storage: local SQLite, schema versioned by SQLx migrations applied at startup;
- encryption: application-side AES-256-GCM, Argon2id key derivation;
- shipped platforms: Linux x86_64 (AppImage), macOS Apple Silicon (DMG), Windows x64 (MSI);
- toolchain: Rust (pinned by
rust-toolchain.toml, minimum supported version declared in Cargo manifests), 2024 edition.
No server is required: secrets never leave the machine.
Local diagnostics and the optional network boundary
Section titled “Local diagnostics and the optional network boundary”Release discovery (heelonvault-app::ui::updates) is a separate network boundary,
independent of sessions and licenses: one HTTPS request to
api.github.com/repos/ppaperso/heelonvault-core/releases/latest, without tokens or vault
data. Consent, last attempt time and latest known stable tag are stored in
update_preferences.json in the UI configuration directory of each operating-system user. Missing or corrupt consent
prevents automatic checks; read/write errors are visible. At startup a 24-hour budget is
checked before launching on Tokio; manual checks bypass that budget. Concurrent checks
are coalesced and disabling checks aborts the in-flight request.
The client rejects redirects and limits connection time to 4 seconds, total request time
to 8 seconds and the body to 64 KiB. Only stable semver tags are accepted; release/download
links are built on the official repository, ignoring URLs and text supplied in the response.
No automatic download or installation takes place.
The security center runs in a background worker using the UI-independent
services::security_center module. It opens only accessible vaults, fetches encrypted items
once per vault and decrypts only password payloads to derive strength and reuse findings.
Password fingerprints are worker-local, zeroized on drop and never included in reports.
Reports contain identifiers, display metadata and typed findings; they are not persisted.
The clock is supplied to the engine, with an inclusive 30-day expiration window.
Cancellation is checked between operations. Session lock invalidates results and clears
the center/editor; a result arriving after lock cannot repopulate the view.
Core remains network-free, enforced by the privacy tests. URL syntax checks are local.
The unpublished heelonvault-url-check workspace crate is a separate network boundary,
invoked by the editor only after consent for that individual check. It receives only the
technical origin, never vault keys, passwords or the URL path/query. Public IP filtering,
validation of every DNS answer, connection to the validated IP and bounded TLS handshakes
limit unintended internal-network access. TLS uses bundled WebPKI roots; no custom CA
override, HTTP request, redirect, browser content or reputation service is involved.
Dropping the check prevents further connection/handshake work; an already-started OS DNS
lookup can finish in Tokio’s blocking pool and its result is discarded.
Online checks reveal at least the hostname and client IP to the resolver/destination. They do not change the offline behavior of the vault or its backup format. A valid TLS certificate does not prove site ownership legitimacy or safety.
Logical Layers
Section titled “Logical Layers”UI (gtk4/libadwaita) -> Business services -> Repositories (SQLx) -> SQLite + migrationsCode Layout (Open Core model)
Section titled “Code Layout (Open Core model)”heelonvault-core/├── crates/│ ├── heelonvault-core/ # Public library (crates.io): models, repositories,│ │ # services, i18n, errors — no UI, no licensing│ ├── heelonvault-url-check/ # Unpublished, isolated consent-based DNS/TLS checker│ ├── heelonvault-app/ # GTK4 binary: assembles core + premium│ │ ├── src/ # main.rs (composition root), ui/ (windows, dialogs, widgets)│ │ ├── migrations/ # SQL migrations applied at startup│ │ ├── assets/ # Embedded CSS, icons, images (GResource)│ │ └── wix/ # Windows installer definition (MSI)│ └── sqlx-shim/ # Local SQLx shim (publish = false)├── linux/ macos/ # AppImage launcher and macOS bundle files├── scripts/ # Dev launcher, Linux system install, SBOM├── docs/ # Published documentation (docs/internal/: maintainers)├── Cargo.toml # Workspace├── clippy.toml # Security Clippy policy└── rust-toolchain.toml # Pinned toolchainheelonvault-coreholds everything that depends neither on the UI nor on licensing. It never initializes atracingsubscriber.heelonvault-appis the Open Core assembler: thepremiumCargo feature (on by default) is the only place that chooses between community implementations andheelonvault-premiumones.heelonvault-premiumis a proprietary component in a separate private repository (multi-user administration, teams, audit report, license verification). Its code ships in the binary; it is activated at runtime by a verified signed license. Its source can be opened for audit under a non-disclosure agreement (see SECURITY.md).
Startup Flow
Section titled “Startup Flow”main.rssets the GTK rendering variables (includingGSK_RENDERER) before starting Tokio.- Tokio runtime and logging are initialized.
- The SQLite database is opened (path resolved as described in Data Paths).
- SQL migrations are applied. The directory is looked up in this order:
HEELONVAULT_MIGRATIONS_DIR, next to the executable, then the current directory. The AppImage, DMG and MSI packages point this variable at their bundled migrations. - Repositories and services are built (premium implementations when the feature is on).
- First run: setup wizard. Otherwise: sign-in screen, then main window.
End of the setup wizard
Section titled “End of the setup wizard”A successful first-run setup does not open a session. bootstrap_flow.rs wipes the account
key (drop of BootstrapResult), sets the flag shared with the close_request handler (otherwise
closing would be treated as a cancellation and quit the app), closes the wizard, then calls
on_bootstrap_completed(username). main.rs switches back to sign-in mode and shows a regular
LoginDialog, on which show_account_created() pre-fills the username.
Key Model
Section titled “Key Model”- Account key (
services/account_key.rs): a random 32-byte key that wraps every vault key of an account. It is only stored encrypted:- under the master password (password envelope,
auth_service); - under the 24-word recovery phrase (domain-separated derivation).
- under the master password (password envelope,
- Vault keys: one per vault, wrapped by the owner’s account key and, for a shared vault, by each member’s.
- Secrets: AES-256-GCM encrypted under their vault key.
Consequences:
- Master password change (
UserService::change_master_password): the account key does not change, only the password envelope is rewritten. Vaults and secrets are not re-encrypted. An older account (pre-account-key format) is migrated during this change: vault keys, TOTP secret and recovery material are rewrapped in a single transaction (rekey_service.rs). - Recovery: the recovery phrase reopens the account key and lets the user set a new password
without losing any vault (
recovery_service.rs,login_dialog/restore_flow.rs). A stored verifier checks the phrase without keeping it.
Main UI View
Section titled “Main UI View”The main window uses a root GtkStack to avoid modal dialogs for the most frequent flows:
entries_view: main secret list;secret_editor_view: inline create / edit;profile_view:Profile & Securitypage;users_view/teams_view: administration (premium).
The sidebar stays visible during profile and edit operations. The profile badge opens a read-only popover with recent sign-in history.
Secret display: cards or list
Section titled “Secret display: cards or list”entries_view relies on a single GtkFlowBox (secret_flow) whatever the display mode (SecretViewMode::Grid / List, defined in ui/view_preferences.rs):
center::apply_view_mode_to_flowconfigures the container (multi-column grid, or one full-width column +main-secret-listCSS class);SecretCard::new(data, mode)builds a card or a compact row from the same building blocks (title, badges, actions), keeping the same action buttons;- the current mode lives in
FilterRuntime::view_mode; the toggle (events::setup_view_mode_handlers) persists the choice then rebuilds the widgets from the last load (SecretListCallbacks::rerender), with no query and no decryption. A full reload only happens when nothing has been loaded yet.
Filtering, sorting, search, counters and keyboard shortcuts are therefore mode-independent. The choice is persisted per installation in ui_view_preferences.json (same directory as ui_main_window_state.json).
Secret list: no plaintext value in the UI
Section titled “Secret list: no plaintext value in the UI”window/refresh.rs builds a single SecretFlowContext shared by two callbacks (SecretListCallbacks): reload (database) and rerender (widgets only). secret_flow.rs works in three stages:
- Load (
refresh_secret_flow, worker thread): for each secret,get_secret()decrypts the value, from which onlyhas_secret,is_weakand a SHA-256 fingerprint are derived; the plaintext stays in the service’sSecretBox(wiped on drop).finalize_rowsflags duplicates then drops the fingerprints inside the loader thread. The master key copy handed over is aZeroizing<Vec<u8>>. - Render (
render_secret_rows): builds cards or rows fromLoadedSecrets(metadata + live usage counters,Rc<Cell<u32>>), kept in the context forrerender. - On-demand copy (
PasswordCopier::copy): snapshot of the session key (refused when locked),open_vault_for_user(re-checks access — a revoked share can no longer be copied),get_secret, copy throughsensitive_clipboard, then wipe. The button is disabled and anin_flightflag blocks re-entry (Ctrl+Cemitsclickedeven on an insensitive button).
Invariant: SecretRowView / SecretRowData never hold a secret value. Login and URL are not encrypted (metadata_json) and can therefore be copied directly. The per-copy overhead (a few SQLite queries + one AES decryption) is imperceptible.
Known limitation: get_secret() re-reads each secret from the database although list_by_vault() just loaded it (N+1 queries). Fixing it needs a new method on the public SecretService trait of heelonvault-core: deferred to a dedicated change.
Clipboard exposure indicator
Section titled “Clipboard exposure indicator”ui/sensitive_clipboard.rs publishes an Exposure (Idle, Decrypting, InClipboard { kind, copied_at, expires_at }) on every change: copy (copy_sensitive(text, SensitiveKind, delay)), expiry, clear_now(), clipboard replaced by another application (changed signal with is_local() == false: the value is wiped at once, leaving the new content alone), and decryption in flight (begin_decrypting() returns an RAII guard held by PasswordCopier).
subscribe()calls the listener at once, then on every change, until it returnsControlFlow::Break. Notifications are emitted after the internal state is released (a listener may call backclear_now()), and subscriptions made during a notification are kept.ui/widgets/clipboard_indicator.rs: header bar button (icon + ring drawn with cairo in aDrawingArea). It only holds weak references, so the subscription ends with the main window rebuilt at each sign-in. The ring is animated (tick callback) only while something is exposed; idle, it costs nothing. Clicking callsclear_now().- Labels only claim what the application controls: never “no secret in memory”.
Runtime Session and Security
Section titled “Runtime Session and Security”PIN Quick-Unlock
Section titled “PIN Quick-Unlock”pin_cache_service: in-memory cache of the master key, protected by Argon2id (8 MiB, t=3) + AES-256-GCM, never persisted to disk.pin_setup_dialog: enable / disable from the profile (4 to 8 digits).pin_unlock_dialog: PIN entry when unlocking after auto-lock.- Safeguards: 3 attempts per cache, hard 12 h expiry, bound to
user_id, random AES-GCM nonce per activation,zeroizewipe onDrop. - PIN badge in the title bar with a session timer (nominal, warning, critical).
Brute-force protection
Section titled “Brute-force protection”- Per username: progressive delay between failed sign-ins.
- Per address (
ip_rate_limit_service,login_attempts_iptable): defaultIpRateLimitPolicyof 20 attempts per one-hour window, then a one-hour lock. Both policies are combined byCombinedRateLimitService;cleanup_expired()purges expired locks. - TOTP: a valid code cannot be replayed immediately.
End of session
Section titled “End of session”- Closing the main window and auto-lock both trigger a clean logout back to the sign-in screen (or to PIN unlock when enabled).
- Sign-in history is stored in
login_history.
Memory hardening
Section titled “Memory hardening”- Keys travel in types that wipe themselves on drop (
SecretBox,Zeroizing).try_pin_unlockreturns aZeroizing<Vec<u8>>; the unlock callback receivesOption<Zeroizing<Vec<u8>>>. clippy.tomlbansunwrap()/expect()onResultandOption: a panic must not be able to expose sensitive data in an error message..cargo/config.tomlenforces-D warningsand-D unsafe_codeacross the workspace.
CSV Import
Section titled “CSV Import”- 3-phase UI: preview, progress (
import_progress_dialog), final summary. - Row-by-row, error-tolerant processing with an aggregated report (imported, failed, per-row details).
- Rejected rows are written to
csv_import_rejects_*.txtin the log directory.
Search
Section titled “Search”Indexed fields: title, login, email, URL, notes, category, tags, secret type.
- case / accent normalization (Unicode);
- field-scoped syntax (
email:,tag:,type:…),field: valueequalsfield:value; - light typo tolerance for long enough terms;
- MultiVault toggle left of the search bar: search all vaults or only the active one.
Data Paths
Section titled “Data Paths”The database path can always be forced with HEELONVAULT_DB_PATH, the log directory with
HEELONVAULT_LOG_DIR. Without them:
| Installation | Database | Logs |
|---|---|---|
| Windows (MSI) | %LOCALAPPDATA%\Heelonys\HeelonVault\data\heelonvault\data\heelonvault-rust.db |
…\heelonvault\logs\ |
| macOS (DMG) | ~/Library/Application Support/fr.Heelonys.HeelonVault/heelonvault/data/heelonvault-rust.db |
…/heelonvault/logs/ |
| Linux (AppImage, “Personal” system install) | ~/.local/share/heelonvault/heelonvault-rust.db |
~/.local/state/heelonvault/logs/ |
| Linux (“Enterprise” system install) | /var/lib/heelonvault/heelonvault-rust.db |
/var/log/heelonvault/ |
Development (scripts/run-dev.sh) |
data/heelonvault-rust-dev.db |
./logs/ |
On Linux, the launchers (the AppImage’s AppRun, the system install’s run.sh) set these
variables; on Windows and macOS the application applies these defaults itself.
- Daily rotation via
tracing-appender; JSON filesheelonvault_YYYYMMDD.log. - Level:
RUST_LOG(takes priority), elseHEELONVAULT_LOG_LEVEL. Default:infofor a release build,debugfor a development build. Sensitive modules (crypto, secrets, authentication, vaults) stay capped atwarnunless explicitly named in the filter. - Logs contain no secret value (enforced by the
privacy_no_secret_in_logstest suite).
Supply Chain
Section titled “Supply Chain”- Zero-warning policy:
cargo auditandcargo deny checkmust be clean before any merge, with no permanent exception. - The former PDF chain (
genpdf) was removed: the premium audit report uses a minimal internal PDF writer that keeps the SHA-256 digest and the Ed25519 signature. - CycloneDX SBOM of the shipped binary, published and attested with every release: see SECURITY.md.
- The
heelonvault-corecrate follows semver:cargo semver-checksin CI rejects an API break without a major version.
Integration tests live in crates/heelonvault-core/tests/ and run against a real SQLite
database. They cover cryptography, authentication and brute force, access control, SQL
injection, absence of secrets in logs, GDPR (erasure, portability), backups and account-key
migration (account_rekey_integration). To run them, see
DEVELOPMENT.md.
