This document describes how Eclosion protects your Monarch Money credentials.

Eclosion requires your Monarch Money email and password to access your financial data. Since Monarch Money does not offer OAuth or API tokens for third-party integrations, direct credential storage is necessary.

To protect your credentials, Eclosion uses user-controlled encryption:

• Your credentials are encrypted locally before storage
• The encryption key is derived from a passphrase (server) or stored in the OS keychain (desktop)
• You can self-host the application for maximum control

The sections below describe the server/self-hosted security model. Desktop users authenticate via OS-level biometrics (Touch ID on macOS) instead of a passphrase.

• Encryption: Fernet (AES-128-CBC with HMAC-SHA256)
• Key Derivation: PBKDF2 with SHA-256, 480,000 iterations
• Salt: 16 bytes (128 bits), randomly generated per user

1. When you first log in with your Monarch credentials, you create an encryption passphrase
2. Your passphrase is used to derive an encryption key using PBKDF2 (a standard key derivation function)
3. Your Monarch email, password, and MFA secret (if applicable) are encrypted with this key
4. The encrypted data and a random salt are stored on the server
5. Your passphrase is never stored: it exists only in memory during your session

Your encryption passphrase must meet these requirements:

• Minimum 12 characters
• At least 1 uppercase letter (A-Z)
• At least 1 lowercase letter (a-z)
• At least 1 number (0-9)
• At least 1 special character (!@#$%^&* etc.)

The encrypted credentials file is stored with restrictive file permissions:

• 0600 (owner read/write only)
• Only the server process can read the file

Even if the server is compromised, your Monarch credentials remain encrypted. An attacker would need both:

1. Access to the encrypted credentials file
2. Your passphrase (which is never stored)

If you forget your passphrase:

• Your encrypted credentials cannot be recovered
• You'll need to re-enter your Monarch credentials and create a new passphrase
• This is by design : it ensures only you can access your credentials

• Your passphrase is kept in server memory only during active sessions
• When the server restarts, you'll need to re-enter your passphrase
• You can manually lock your session at any time
• Sessions automatically expire after 30 minutes of inactivity (configurable)

During an active session, your passphrase is stored in the Flask session cookie to enable credential decryption for API calls. This is a security/convenience trade-off:

How it works:

• Flask session cookies are signed and encrypted using the server's SESSION_SECRET
• The passphrase is transmitted in encrypted form with each request
• The server decrypts the session to access the passphrase when needed

Mitigations:

• Session cookies are HttpOnly and Secure (HTTPS only in production)
• Sessions expire after inactivity
• The SESSION_SECRET must be a strong, random value (generated at first run)
• Locking your session immediately clears the passphrase from the cookie

Why this design:

• Avoids storing the passphrase in plaintext on the server filesystem
• Enables stateless server restarts (session survives server bounce via cookie)
• Follows Flask's standard session management pattern

For maximum security, you can reduce SESSION_TIMEOUT_MINUTES in your environment configuration or manually lock your session when stepping away.

For maximum security and control, you can run Eclosion on your own infrastructure:

1. Your credentials never leave your own server
2. You control all aspects of the deployment
3. You can audit the open-source code

See the documentation for self-hosting instructions.

Monarch Money does not currently provide:

• OAuth authentication for third-party apps
• Personal access tokens
• API keys

Direct credential authentication is the only available method. Eclosion uses strong encryption to mitigate the risks of credential storage.

If you discover a security vulnerability, please report it responsibly:

1. Report privately via GitHub Security Advisories
2. Do not disclose publicly until addressed
3. Allow reasonable time for a fix

• core/encryption.py : Encryption utilities
• state/state_manager.py : CredentialsManager class
• blueprints/auth.py : Authentication endpoints
• blueprints/security.py : Security status endpoints

• POST /auth/login : Validate Monarch credentials (does not store)
• POST /auth/set-passphrase : Encrypt and save credentials with passphrase
• POST /auth/unlock : Decrypt credentials with passphrase
• POST /auth/lock : Clear session (keeps encrypted credentials)
• POST /auth/logout : Clear both session and stored credentials
• GET /security/status : Get security configuration info