Authentication & Security

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• src/lib/actions/auth.ts
• src/proxy.ts
• PRODUCT.md
• src/lib/help/faq.ts
• e2e/specs/15-security-factors.spec.ts
• e2e/specs/12-session-revocation.spec.ts

Hearth implements a multi-layered security model designed for a privacy-conscious, self-hosted environment. The system manages household-wide data access using NextAuth v5, multi-factor authentication, and strict request validation to protect sensitive personal and financial information.

The architecture centers on a household-wide access model where all invited members see shared records, while administrative actions remain restricted to the ADMIN role. Security is enforced through server-side session validation, encrypted-at-rest backups, and a Content Security Policy (CSP) that prevents unauthorized cross-origin interactions.

Identity and Access Management

Hearth uses a closed, invite-only system for user management. There is no public sign-up; instead, administrators invite new members via email or by setting temporary passwords.

Roles and Permissions

The system defines three primary roles that govern user capabilities:

Role	Permissions
ADMIN	Full access to records; manages household members, webhooks, backups, and modules.
MEMBER	Can add, edit, and delete household records (contracts, trips, properties, etc.).
READONLY	Can view all household data but cannot perform any write operations.

Sources: src/lib/help/faq.ts:25-30, CLAUDE.md:129-136

Authentication Factors

Hearth supports several authentication methods to verify user identity:

• Credentials: Standard email and password login. Passwords are hashed using bcrypt.
• TOTP (2FA): Time-based One-Time Passwords using standard authenticator apps.
• Passkeys (WebAuthn): Hardware or biometric-based second factors, managed via @simplewebauthn.

Sources: CLAUDE.md:131-135, src/lib/actions/auth.ts:133-142, e2e/specs/15-security-factors.spec.ts:32-41

The authentication flow requires valid credentials followed by any configured second factors before minting a JWT session. Sources: src/lib/actions/auth.ts:145-185, e2e/specs/15-security-factors.spec.ts

Session Management and Revocation

Sessions are maintained as JSON Web Tokens (JWT). To prevent stale privileges, Hearth validates tokens against the database on every read.

Immediate Revocation Logic

A sessionVersion counter exists on the user record. If any of the following occur, the version increments, immediately invalidating all existing JWTs for that user:

1. The user changes their password.
2. An administrator updates the user's role.
3. The account is deleted.

Sources: e2e/specs/12-session-revocation.spec.ts:7-11, src/lib/actions/auth.ts:354-360, src/lib/actions/auth.ts:316-320

Infrastructure Security

Hearth employs several infrastructure-level protections to secure the web application and its data.

Middleware Security Proxy

The system uses a security proxy (src/proxy.ts) to intercept requests and apply defensive measures:

• Content Security Policy (CSP): Implements a nonce-based policy. It uses strict-dynamic for scripts and restricts frame-ancestors to none.
• CSRF Protection: Performs a defense-in-depth origin check for REST API endpoints.
• HSTS: Applies Strict-Transport-Security headers if the connection is HTTPS.
• Public Path Gating: Redirects unauthenticated requests to /login unless the path is explicitly marked public (e.g., /api/cron, /setup).

Sources: src/proxy.ts:25-50, src/proxy.ts:98-115, src/proxy.ts:122-135

Data Encryption

Sensitive data is encrypted at rest using AES-256-GCM, gated by a required ENCRYPTION_KEY environment variable:

• Cloud AI Keys: User-provided API keys for Anthropic, Google, or OpenAI.
• Backups: Full SQLite snapshots are encrypted before they are uploaded to S3 or SFTP destinations.

Sources: CLAUDE.md:79-84, PRODUCT.md:120-123, PRIVACY.md:52-53

Network & Rate Limiting

To prevent brute-force attacks, Hearth implements rate limiting on sensitive actions.

Action	Throttle Key	Limit Behavior
Login	Email + IP Address	Throttles after repeated failures; successful login resets the limit.
TOTP	Email + IP Address	Separate throttle for second-factor entry.
Password Reset	IP Address	Caps total reset requests to prevent email spam and enumeration.

Sources: src/lib/actions/auth.ts:145-160, src/lib/actions/auth.ts:405-410

The rate-limiting sequence ensures that login attempts are validated against both origin and frequency before cryptographic checks occur. Sources: src/lib/actions/auth.ts:145-185, src/proxy.ts:122-130

Security Configuration Summary

Most security features are activated by the presence of specific environment variables.

Variable	Security Function
ENCRYPTION_KEY	Gates 2FA, AI key encryption, and backup encryption.
CRON_SECRET	Required for the /api/cron endpoint to function.
MCP_TOKEN	Required for the Model Context Protocol (MCP) server read-only access.
APP_URL	Acts as the Relying Party ID for WebAuthn/Passkeys.
SETUP_TOKEN	Protects the initial /setup route from being claimed by unauthorized users.

Sources: CLAUDE.md:164-167, PRODUCT.md:95-100, src/lib/actions/auth.ts:68-72

Hearth's security posture prioritizes household-wide transparency while enforcing strict administrative boundaries and multi-factor authentication to protect the self-hosted environment.