update docs

docs/thijooree/02-lock-screen.md

@@ -0,0 +1,82 @@
+# Lock Screen
+
+`LockActivity` is shown whenever the app is locked — on cold start (when credentials exist), after the autolock timer fires, or when the user taps the lock icon in the toolbar.
+
+---
+
+## Authentication Methods
+
+The app attempts authentication in priority order:
+
+1. **Biometrics** — if enrolled and enabled, `BiometricPrompt` is presented automatically on open
+2. **PIN** — numeric keypad
+3. **Pattern** — `PatternView` grid
+
+The user can switch between biometric and PIN/pattern manually.
+
+---
+
+## Biometric Authentication
+
+Uses Android `BiometricPrompt` with `BIOMETRIC_WEAK` (fingerprint or face depending on device). A successful biometric result sets `app.isUnlocked = true` and calls `MainActivity` to route to `HomeActivity`.
+
+On biometric failure or cancellation the screen falls back to PIN/pattern entry.
+
+---
+
+## PIN Entry
+
+- A custom on-screen numeric keypad (0–9 + backspace + confirm)
+- The entered digits are shown as filled/unfilled circles (no digit echo)
+- Confirm fires verification immediately when the correct number of digits is entered
+
+---
+
+## Pattern Entry
+
+- The same `PatternView` widget used in onboarding, in verify-only mode
+- The drawn pattern is hashed and compared against the stored derived key
+
+---
+
+## Verification
+
+The entered PIN or pattern is run through **PBKDF2-HMAC-SHA256** with the stored salt and compared to the stored hash. On match:
+
+1. `app.isUnlocked = true`
+2. `LockActivity` finishes
+3. `MainActivity` routes to `HomeActivity`
+
+On mismatch the attempt counter increments and an error shake animation plays.
+
+---
+
+## Brute-Force Protection
+
+| Threshold | Behaviour |
+|---|---|
+| 1–4 wrong attempts | Error label shown, counter visible |
+| 5 wrong attempts | 30-second lockout; keypad/pattern disabled |
+| After lockout | Counter resets; user may try again |
+
+The attempt counter and lockout timestamp are stored in **plain** `SharedPreferences` (not encrypted) — a known limitation documented in the security audit. The app does not wipe credentials after repeated failures.
+
+---
+
+## `app.isUnlocked` Guard
+
+`app.isUnlocked` is an in-memory flag that is `false` on every process start. Even if an attacker bypasses `LockActivity` via `adb`, `HomeActivity` checks this flag and re-fires `LockActivity` on resume if it is `false`. This prevents cold-start bypass.
+
+---
+
+## Screenshot Protection
+
+`FLAG_SECURE` is set on `LockActivity`'s window, preventing screenshots and screen recording. This is always on for the lock screen regardless of the user's global screenshots setting.
+
+---
+
+ 
+
+---
+
+[← Onboarding](01-onboarding.md)     **Next →** [Login](03-login.md)