UI & Customization

Security Lock & Screen Protection

Local PIN validation, biometric master key stashing, idle window timeouts, and app-wide screenshot blocks.

Overview

Wiltkey implements multi-layered security gates to protect offline data from local access. Security controls include cryptographically validated PIN gates, stashed hardware biometric keys, idle timeout windows, and system-level screen layout protection.

Security Architecture

1. PIN Lock & Key Derivation

Authentication verifies a user's PIN to set the active masterKeyHex in RAM. The PIN is hashed concatenated with a local salt over 5000 iterations of SHA-256. The validation check compares the derived hash against pinValidationHash:

derivedHash = SHA-256(derivedKey)

If valid, the derived key is assigned as the master key to decrypt incoming and historical SQLite database payloads.

2. Biometric Key Stashing & 4-Hour Idle Window

For convenience, users can enable fingerprint unlock. Opting in prompts the OS biometric manager and stashes the PIN-derived master key hex inside the Android Keystore backed secure store:

key = wk_bio_master_key (FlutterSecureStorage, encryptedSharedPreferences: true)

4-Hour Idle Gate: To prevent long-term exposure, biometrics are only allowed within a 4-hour window from the last active unlock (_biometricMaxIdleMs = 4 * 60 * 60 * 1000). If the idle age is exceeded, biometrics are blocked, and the user must type the full PIN to re-activate stashing.

3. Screenshot Blocking (FLAG_SECURE)

Wiltkey blocks screenshots, screen recording, and system-level app review layout previews app-wide. The block is configured at the Android OS Window Manager layer inside the native wrapper:

                        android/app/src/main/kotlin/.../MainActivity.kt
                        KOTLIN
                    

class MainActivity : FlutterFragmentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // Blocks screenshots and screen recordings app-wide
        window.addFlags(WindowManager.LayoutParams.FLAG_SECURE)
        super.onCreate(savedInstanceState)
    }
}

This tells the OS window manager to treat the application window as secure: screenshots fail, screen recordings yield a black video, and the app preview is hidden in the OS "recents" apps overview screen.

Key Files & Symbols

File Path	Symbol Name	Description
`android/.../MainActivity.kt`	`MainActivity`	Enforces the window-level `FLAG_SECURE` parameter. Inherits from `FlutterFragmentActivity` to enable local_auth bindings.
`lib/core/state_auth.dart`	`unlockApp()`	Derives KDF key, verifies validation hashes, and updates master key stashes in memory.
`lib/core/state_auth.dart`	`biometricAllowedNow()`	Enforces the 4-hour idle window lock.
`lib/core/auth/biometric_auth.dart`	`BiometricAuth`	Interface stashing master keys in Android Keystore via `FlutterSecureStorage`.

Gotchas & Edge Cases

⚠️ KEYSTORE INVALIDATION ON REBOOT
Because biometrics stash the master key in Android Keystore, a device reboot, OS configuration change, or update to the system's fingerprint database will invalidate the stashed Keystore keys. The stashed key becomes unreadable, and the client must fallback to the PIN code to restore session access.