Security Guide
Scope: the HeelonVault desktop application (crates/heelonvault-core, crates/heelonvault-app).
Language note / Note de langue:
- primary wording is English for technical consistency;
- key disclosure and compliance terms are mirrored in French when useful.
1. Security Scope and Threat Model
Section titled “1. Security Scope and Threat Model”HeelonVault is a local-first desktop password manager.
Security goals:
- protect vault secrets at rest;
- protect authentication material (master password derivatives, not plaintext);
- limit brute-force attempts on login;
- reduce accidental leaks in UI and logs;
- preserve session safety (auto-lock and explicit logout).
Security-center and link-check boundaries
Section titled “Security-center and link-check boundaries”The security center is local: strength/reuse checks concern password items only; expiration and URL syntax concern item metadata. Missing/corrupt data is reported explicitly, not counted as healthy. Reports do not contain plaintext or password fingerprints and are cleared on session lock. They do not certify absence of compromise.
URL network checks are disabled until the user consents to an individual check in the
editor. The separate heelonvault-url-check crate resolves and contacts only public
destinations and validates a TLS handshake using bundled trusted roots. It sends no HTTP
request, path, query, credential or cookie. The DNS resolver and destination can observe
the hostname and client IP. Local/intranet destinations are blocked. A successful TLS
check means only that the certificate validated for that host at that time; reputation,
revocation status via online OCSP/CRL, page existence and site legitimacy are not assessed.
No reputation provider is enabled. Core’s no-network invariant remains tested.
Optional application update checks run in the App layer, not Core. Automatic checks require explicit consent, stored per operating-system user, and are limited to one attempt every 24 hours at startup; the profile offers a one-off manual check. Requests go only to the official GitHub releases API over HTTPS, with no token, vault, account or license data. GitHub can observe the client IP. Redirects are rejected; request duration and response size are bounded. Only stable semver releases are considered, and release links use the fixed official repository. The feature neither downloads nor installs packages and does not attest their authenticity. Network or configuration errors are never presented as an up-to-date result.
Main assumptions:
- if the OS account is fully compromised while the app is unlocked, attacker impact remains high;
- the project focuses on local storage security, not cloud account security.
2. Cryptography in Rust
Section titled “2. Cryptography in Rust”Current primitives used in src/services/crypto_service.rs:
- KDF: Argon2id (v=19)
- default KDF params: memory 64 MiB, time cost 3, parallelism 1
- derived key size: 32 bytes
- random salt size: 32 bytes
- encryption: AES-256-GCM
- nonce size: 12 bytes (fresh random nonce per encryption)
- RNG: getrandom (OS CSPRNG)
- sensitive buffers: secrecy + zeroize/Zeroizing patterns
Implementation notes:
- decryption/authentication failures return generic crypto errors;
- salts and keys are never stored as plaintext passwords;
- key derivation and encryption are isolated in dedicated services.
3. Authentication and Password Material
Section titled “3. Authentication and Password Material”Current auth model in src/services/auth_service.rs:
- plaintext passwords are converted to secret strings in memory only;
- password verification uses constant-time byte comparison;
- credentials are stored as a versioned envelope:
- envelope version byte
- salt length + hash length
- Argon2id salt and derived hash bytes
- persisted value in database: users.password_envelope (binary)
Important:
- no plaintext password is persisted;
- changing password rotates salt and hash;
- auth service supports shutdown signaling to block operations during controlled shutdown.
4. Login Identifier UX and Security
Section titled “4. Login Identifier UX and Security”Login now accepts a single identifier field with resolution order:
- username (exact logical match, case-insensitive after trim)
- email (if present)
- display_name (if present)
Security behavior:
- lock policy is applied on the resolved canonical username;
- failed attempts increment the policy counter for that account;
- unknown identifier is treated as invalid credentials.
5. Brute-force and Session Controls
Section titled “5. Brute-force and Session Controls”Current lock controls in src/services/auth_policy_service.rs:
- threshold: 5 failed attempts
- lock window: 5 minutes
- counters are persisted in auth_policy table
- successful login resets failed_attempts and last_attempt_at
Current session controls:
- auto-lock delay per user: allowed values 0, 1, 5, 10, 15, 30 minutes
- default auto-lock delay: 5 minutes
- app returns to login screen on logout/auto-lock
- close-window path triggers secure logout behavior
- login flow enforces TOTP verification when 2FA is enabled for the resolved account
6. Password Policy and ANSSI Positioning
Section titled “6. Password Policy and ANSSI Positioning”This project follows an internal baseline inspired by ANSSI guidance (long unique passphrases, no reuse, context-based hardening).
Current technical rules in Rust:
- password service policy (generator/validator):
- min length 16, max 128
- at least one lowercase, uppercase, digit, symbol
- no whitespace
- generated passwords default to length 24
Current master password change rule in user flow:
- minimum length check set to 16 before update.
Security recommendation for operations:
- for admin and sensitive environments, use passphrases >= 16 chars;
- all entry points now aligned to a unified >= 16 policy.
7. Data Protection Boundaries
Section titled “7. Data Protection Boundaries”Data encrypted with AES-256-GCM:
- secret payloads in vault items (passwords and sensitive blobs)
- key envelopes used by vault service
- persisted password envelopes for authentication material
Data that may remain in clear text for UX/indexing reasons:
- some metadata fields such as labels/titles/tags/URLs.
Operational recommendation:
- do not place highly sensitive values in metadata fields intended for search/display.
8. 2FA Status
Section titled “8. 2FA Status”2FA/TOTP is active end-to-end in the current runtime flow.
Current behavior:
- users can activate/deactivate TOTP in profile/security UI;
- login requires password verification first, then TOTP code when enabled;
- TOTP invalid/missing code returns explicit user feedback and blocks login;
- TOTP secret is stored encrypted in database;
- migration handling keeps backward compatibility for legacy encrypted payloads.
Audit position:
- MFA can now be claimed as enforced for accounts with TOTP enabled.
8.1 First-Admin Bootstrap and Recovery Key
Section titled “8.1 First-Admin Bootstrap and Recovery Key”When the application starts with no admin account, a 3-step bootstrap wizard is presented:
- Identity step — the user provides a username and password (minimum strength enforced, confirmation required);
- Oath step — a 24-word BIP39-style mnemonic recovery phrase is generated via
BackupService::generate_recovery_key(). The user must verify two randomly drawn words before confirming, proving they have recorded the phrase; - Pending step —
admin_service::bootstrap_first_admin_with_recovery()runs in a background thread: it creates the account key, stores it encrypted under the password and under the recovery phrase, and stores a verifier of the phrase. On success no session is opened: the account key is wiped from memory and the regular sign-in screen is shown, username pre-filled.
Recovery key security properties:
- generated from a cryptographically secure RNG (
getrandom); - the phrase itself is never persisted in the database (only the account key sealed under it, and a verifier); it is the user’s sole responsibility to store it safely;
- clipboard copy sets a 60-second auto-clear timer; the clipboard is also wiped when the dialog closes;
- on Linux/macOS, the clipboard content is served on demand through a custom provider that itself starts returning empty text once expired, so no unzeroized copy of the secret persists in memory beyond expiry. On Windows, GDK’s clipboard backend (OLE/
IDataObject) crashes with that same provider (STATUS_ACCESS_VIOLATIONinsidelibgtk-4-1.dll, reproduced consistently); Windows instead uses GDK’s built-in eager content provider, so the secret is copied into GDK-owned memory at copy time and cleared by overwriting the clipboard outright at expiry, rather than by the provider self-clearing on read. Seecrates/heelonvault-app/src/ui/sensitive_clipboard.rs. - after bootstrap, the recovery key can be re-exported at any time from
Profile & Security(admin only), generating a new phrase wrapped in the same secure export dialog; - backup export/import (
.hvbfiles) is gated behindBackupApplicationServicewhich enforces RBAC: only admin-role users may perform these operations.
9. Logging and Security Events
Section titled “9. Logging and Security Events”Current event coverage includes:
- successful login history (table login_history);
- auth failure threshold events (critical counters);
- policy reset/update traces.
Logging rules:
- never log plaintext secrets;
- keep technical details sufficient for incident triage without sensitive payload leakage.
10. Security Testing
Section titled “10. Security Testing”Minimum test routine before release:
-
cargo check
-
cargo test
-
targeted security suites:
tests/security_auth.rs tests/security_crypto.rs tests/totp_activation_integration.rs tests/twofa_messages_integration.rs tests/backup_security_integration.rs
Recommended manual checks:
- verify login lock behavior after repeated failures
- verify auto-lock behavior and forced return to login
- verify password change rotates auth envelope and old password no longer works
- verify login via username, display name, and email
11. Vulnerability Disclosure
Section titled “11. Vulnerability Disclosure”Do not open public issues for security vulnerabilities.
Primary contact channel / Canal de contact principal:
Email subject format / Format d’objet:
SECURITY-HeelonVault : short title
Confidentiality recommendation / Recommandation de confidentialite:
- avoid sending plaintext secrets, full database files, or master passwords;
- share minimal proof-of-concept and redacted logs;
- if you need encrypted exchange, request secure keying instructions in your first message.
Please include / Merci d’inclure:
- impacted version
- environment
- reproduction steps
- expected vs actual behavior
- impact assessment
- proof of concept if available
Target response process (SLA) / Delais cibles de reponse:
- acknowledgment within 24h
- initial triage and severity classification within 3 business days
- status update cadence at least every 7 days until closure
11.1 Mini CVSS Prioritization Matrix
Section titled “11.1 Mini CVSS Prioritization Matrix”Use this matrix for fast intake prioritization before full CVSS scoring.
| Priority | Exploitability | Impact on CIA | Operational target |
|---|---|---|---|
| P1 (Critical) | trivial or low-complexity remote exploit, no strong preconditions | high impact on confidentiality and/or integrity, or major availability loss | immediate handling, mitigation/fix target <= 7 days |
| P2 (High) | realistic exploit with limited prerequisites | moderate/high impact on one or more of confidentiality, integrity, availability | accelerated handling, mitigation/fix target <= 14 days |
| P3 (Medium) | exploit requires specific conditions, chaining, or user interaction | limited-to-moderate impact on confidentiality, integrity, availability | planned handling, mitigation/fix target <= 30 days |
| P4 (Low) | difficult exploit path or theoretical only | low impact on confidentiality, integrity, availability | best effort in regular release cycle |
CIA interpretation:
- confidentiality: unauthorized disclosure of secrets, metadata, keys, or sensitive logs;
- integrity: unauthorized modification of credentials, vault entries, or policy controls;
- availability: lockout, crash loop, data corruption, or sustained denial of service.
Remediation targets by severity:
- Critical: mitigation or fix target within 7 days
- High: mitigation or fix target within 14 days
- Medium: mitigation or fix target within 30 days
- Low: best-effort in regular release cycle
Coordinated disclosure policy:
- public disclosure only after a fix or mitigation is available, unless required by law;
- reporters are credited (optional) after coordinated disclosure.
12. Compliance and Hardening Roadmap
Section titled “12. Compliance and Hardening Roadmap”Completed:
- MFA lifecycle hardened: TOTP activation/deactivation fully implemented
- Backup/recovery workflow secured: recovery key generation with clipboard auto-wipe, mandatory verification, RBAC-gated backup operations
- Audit trail for admin-sensitive operations (audit_log table, migration 0013)
Near-term priorities:
- unify master password policy to >= 16 across all flows
- document hardening profiles (standard, admin, high assurance)
Reference standards:
- ANSSI password and authentication recommendations
- OWASP Password Storage Cheat Sheet
- NIST SP 800-63B
13. Supply Chain Security and SBOM
Section titled “13. Supply Chain Security and SBOM”Automated gates in CI (.github/workflows/supply-chain.yml, on every push to
main, every pull request, and daily):
cargo-deny: zero-tolerance on known vulnerabilities (RUSTSEC advisories), license allow-listing (permissive licenses only), and a duplicate-dependency-version ban (with explicitly documented, reviewed exceptions indeny.tomlfor genuine upstream ecosystem splits).- SBOM (Software Bill of Materials): a CycloneDX 1.4 JSON inventory of
every dependency actually shipped in the
heelonvaultbinary — including platform-specific ones (e.g. Windows-only crates) and the privateheelonvault-premiumcomponent, not just the publicheelonvault-corecrate. Regenerated viascripts/generate-sbom.shand committed assbom.cyclonedx.jsonat the repository root; thecheck-sbomCI job regenerates it on every relevant push and fails the build if the committed file has drifted from the actual dependency graph. - Signed release SBOM: on every
vX.Y.Ztag,.github/workflows/sbom-release.ymlattachesheelonvault-sbom-<tag>.cyclonedx.jsonand its.sha256to the GitHub release, with a Sigstore build-provenance attestation:gh attestation verify heelonvault-sbom-<tag>.cyclonedx.json --repo ppaperso/heelonvault-core. - Proprietary component:
heelonvault-premium(license verification, administration, teams, audit report) is proprietary and its source is not public. It is listed in the SBOM with its dependencies. On request, a customer’s security teams (IT department, CISO, appointed auditor) can be given read access to that source for audit purposes, under a non-disclosure agreement or equivalent: contactsupport@heelonys.fr.
Regulatory context: the EU Cyber Resilience Act (CRA) introduces SBOM and vulnerability-handling obligations for manufacturers of products with digital elements, phased in through 2026–2027. This tooling is a technical practice that supports that posture (an accurate, CI-enforced, always-current component inventory) — it is not itself a legal compliance determination or certification. Confirm applicability and specific obligations with legal counsel.
