Security & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/java/io/github/mojri/hesabyar/auth/AuthManager.kt
- app/src/main/java/io/github/mojri/hesabyar/auth/PinStorage.kt
- app/src/main/java/io/github/mojri/hesabyar/auth/BiometricHelper.kt
- rust/hesabyar-core/src/crypto.rs
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/SettingsScreen.kt
- rust/hesabyar-core/src/ai_validation.rs
Security in the Hesabyar project is built on a multi-layered architecture that combines local Android authentication mechanisms with high-performance cryptographic primitives implemented in the Rust core. The system ensures data privacy through mandatory PIN or biometric verification and protects against malicious AI-generated content through strict sanitization protocols.
The primary goal of the Security & Authentication system is to provide a "lock" mechanism for the application, ensuring that financial data remains inaccessible to unauthorized users on the device. It leverages hardware-backed biometric sensors where available and falls back to a secure 6-digit PIN storage system.
Authentication Framework
The authentication framework is orchestrated by the AuthManager, which maintains the application's locked state and handles transitions between locked and unlocked modes based on user interactions and timeouts.
Architecture and Components
The system relies on three primary components:
- AuthManager: A singleton service managing the
isLockedstate and session timeouts. - PinStorage: Handles the persistence and verification of the user's secret PIN.
- BiometricHelper: Interfaces with the Android Biometric library to provide fingerprint and face unlock capabilities.
The following diagram illustrates the high-level authentication flow:
PIN Management
The application uses a 6-digit PIN for primary local authentication. The PinStorage class manages the lifecycle of this PIN, including creation, verification, and clearing. PINs are verified synchronously via PinStorage.verifyPin.
| Feature | Requirement |
|---|---|
| PIN Length | Exactly 6 digits |
| Storage Method | Encrypted SharedPreferences (via getPrefs) |
| Verification | Boolean comparison against stored value |
Sources: app/src/main/java/io/github/mojri/hesabyar/auth/PinStorage.kt:15-60, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SettingsScreen.kt:630-660
Session and Timeout Logic
The AuthManager implements a session timeout mechanism to re-lock the application after a period of inactivity. By default, this timeout is set to 30 minutes.
Key Logic and Functions
- onUserInteraction(): Resets the lock timer whenever the user interacts with the UI.
- lockTimeoutMs: Configurable duration (in milliseconds) before the app automatically locks.
- lockRunnable: A scheduled task that triggers the
lock()function when the timer expires.
Cryptography and Data Integrity
The project utilizes a Rust-based core (hesabyar-core) for performance-critical security operations. This includes checksum generation for data integrity and AES-256-GCM encryption.
Rust Cryptographic Primitives
The crypto.rs module provides standard interfaces for:
- AES-256-GCM: Used for encrypting backups and sensitive data strings.
- SHA-256 Checksums: Ensures that imported backup files have not been tampered with.
| Operation | Implementation | Context |
|---|---|---|
| Checksum | computeChecksumSync | Data Integrity (Backup/Restore) |
| Verification | verifyChecksumSync | Import Validation |
| Encryption | AES-256-GCM | Data Privacy |
Sources: rust/hesabyar-core/src/crypto.rs:1-50, app/src/main/java/io/github/mojri/hesabyar/rust/RustBridge.kt:165-175
AI Security and Sanitization
To prevent injection attacks and ensure the safety of AI-generated content (Advice and Forecasts), the system implements a strict validation pipeline in the Rust core.
Sanitization Process
The validate_ai_advice function in ai_validation.rs performs the following security checks on free-form AI text:
- Tag Stripping: Case-insensitive removal of dangerous patterns such as
<script>,</script>, andjavascript:. - Length Clamping: Truncating responses that exceed
MAX_ADVICE_LENGTH(10,000 characters) to prevent memory exhaustion. - Persian Character Check: Warning if no Persian characters are detected, ensuring content relevance.
Security Configuration
Users can manage security settings through the application's Settings screen. These settings allow for the activation of PIN locks, biometric tests, and the configuration of AI providers.
Settings Management
- SecuritySection: Provides UI components to toggle the PIN lock and test biometric authentication.
- Biometric Testing: Uses
BiometricHelper.authenticateto verify that the device's hardware is compatible and functioning. - Encrypted Preferences: The
AiProviderConfiguses encrypted storage to protect sensitive API keys for Gemini, OpenRouter, and custom providers.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/SettingsScreen.kt:530-600, app/src/main/java/io/github/mojri/hesabyar/api/AiProviderConfig.kt:119
The Security & Authentication system in Hesabyar provides a robust defense-in-depth approach. By combining Android's native biometric capabilities with high-speed Rust-based encryption and sanitization, the application ensures that financial records are protected both from physical access and from malicious digital input.