Privacy & Security
Relevant source files
The following files were used as context for generating this wiki page:
Hearth functions as a self-hosted household system of record, prioritizing data ownership and privacy. The system operates without a central Hearth-operated backend; the developer never receives or stores user data. Users maintain full control over their database, local file storage, and third-party integrations.
The platform employs a "household-wide" data model where all members share visibility of records, while roles gate administrative actions. Security measures include AES-256-GCM encryption for sensitive keys and offsite backups, multi-factor authentication, and mTLS support for mobile connections.
Sources: PRIVACY.md:3-8, PRODUCT.md:7-12, CLAUDE.md:143-156
Architecture and Data Ownership
Hearth is primarily distributed as a Docker Compose application for self-hosting. Data is stored in an instance-specific SQLite database and local file storage. The mobile applications (Android/iOS) function as thin wrappers that point to the user's self-hosted server URL.
Data Flow and Storage
The following diagram illustrates how data remains within the user's controlled environment versus when it leaves for optional integrations.
Data storage and egress logic. Sources: PRIVACY.md:11-40, PRODUCT.md:25-32
Privacy-Preserving Features
- Self-Hosted Document Extraction: The extraction pipeline prioritizes local text extraction and OCR (pdftotext/Tesseract). It only uses cloud AI if the user explicitly configures an API key.
- Encrypted Backups: Database snapshots are encrypted with AES-256-GCM using a user-configured
ENCRYPTION_KEYbefore leaving the server. - Zero Telemetry: The application contains no analytics, tracking SDKs, or advertising.
Sources: PRIVACY.md:42-43, PRODUCT.md:37-40, CLAUDE.md:104-106
Authentication and Access Control
Hearth implements a role-based access control (RBAC) system focused on household administration rather than data siloing.
User Roles
| Role | Permissions |
|---|---|
| ADMIN | Full access, including user management, webhooks, backups, and module toggles. |
| MEMBER | Can create, edit, and delete records (contracts, trips, etc.). |
| READONLY | Can view all household data but cannot perform any write actions. |
Sources: PRODUCT.md:33-35, CLAUDE.md:143-149, src/lib/help/faq.ts:33-37
Multi-Factor Authentication (MFA)
The system supports two independent second factors:
- WebAuthn Passkeys: Uses biometric data (FaceID, TouchID) or security keys.
- TOTP: Standard time-based one-time passwords via authenticator apps.
Sources: PRODUCT.md:36-37, CLAUDE.md:92-100, src/app/(app)/settings/page.tsx:109-115
Mobile Security
The mobile shell (Capacitor) introduces specific security layers for both connected and standalone modes.
Mobile Security Flow
Mobile connection and certificate flow. Sources: PRIVACY.md:18-24, ios-shell/www/app.js:189-204
Standalone Mode Security
When running in "Standalone Mode," the mobile app stores data in an encrypted native SQLite database using @capacitor-community/sqlite. Document files are stored in app-private storage and are not accessible by other applications.
Sources: ios-shell/www/app.js:231-253, CLAUDE.md:126-130
Encryption Management
Hearth uses a single ENCRYPTION_KEY environment variable to gate high-security features. If this key is not present, features requiring encryption are disabled in the UI.
Encrypted Components
- User API Keys: API keys for cloud providers (Anthropic, OpenAI, etc.) are encrypted at rest.
- Offsite Backups: Full SQLite snapshots are encrypted before transmission to S3 or SFTP destinations.
- Mobile Standalone DB: Uses a passphrase-protected encrypted SQLite database.
Sources: PRODUCT.md:37-40, CLAUDE.md:113-115, ios-shell/www/app.js:255-259
Technical Constraints
- The
ENCRYPTION_KEYmust be configured for TOTP to be available. APP_URLmust be set to enable WebAuthn passkeys (used as the Relying Party ID).- MCP (Model Context Protocol) access is gated by a mandatory
MCP_TOKEN.
Sources: CLAUDE.md:94-96, CLAUDE.md:120-123, src/app/(app)/settings/page.tsx:112-114
Summary
Security in Hearth is built on the principle of local control. By default, data never leaves the household's infrastructure. When external integrations are enabled, Hearth provides tools like AES-256 encryption and mTLS to protect data in transit and at rest. The administrative roles ensure that while data is shared among household members, critical system configurations remain restricted to administrators.