docs: update migration guide and changelog for biometric authentication changes

Author: ioannisa

CHANGELOG.md

@@ -29,52 +29,8 @@ All notable changes to KSafe will be documented in this file.
   - `clearBiometricAuth(scope)` - Clear only a specific scope
 
 ### Changed
-- **Removed `useBiometrics` parameter** from all storage APIs (`get`, `put`, `getDirect`, `putDirect`)
-- Biometric verification is now a separate step you control explicitly
 - **iOS thread safety improvements** - Biometric callbacks now always execute on Main thread
 
-### Migration from 1.2.x
-
-#### Before (1.2.x)
-```kotlin
-// Biometrics tied to storage
-ksafe.put("key", value, useBiometrics = true)
-val data = ksafe.get("key", default, useBiometrics = true)
-```
-
-#### After (1.3.0)
-```kotlin
-// Biometrics as a separate verification step
-ksafe.verifyBiometricDirect("Authenticate to save") { success ->
-    if (success) {
-        ksafe.putDirect("key", value)
-    }
-}
-
-// Or with suspend function
-if (ksafe.verifyBiometric("Authenticate to read")) {
-    val data = ksafe.get("key", default)
-}
-
-// With duration caching (60 seconds, scoped to ViewModel)
-ksafe.verifyBiometricDirect(
-    reason = "Authenticate",
-    authorizationDuration = BiometricAuthorizationDuration(
-        duration = 60_000L,
-        scope = viewModelScope.hashCode().toString()
-    )
-) { success ->
-    if (success) { /* ... */ }
-}
-```
-
-### Benefits of New Architecture
-- **Full control** over when biometric prompts appear
-- **Reusable** - Same biometric helper protects any action
-- **Flexible caching** - Avoid prompt fatigue with duration caching
-- **Scoped invalidation** - Auth tied to ViewModel lifecycle or custom scopes
-- **Cleaner separation** - Storage and authentication are independent concerns
-
 ---
 
 ## [1.2.0] - 2025-01-15

README.md

@@ -929,44 +929,6 @@ The iOS test app demonstrates:
 
 ## Migration Guide
 
-### From v1.2.x to v1.3.0
-
-#### Biometric API Changes
-The `useBiometrics` parameter has been **removed** from all storage APIs. Biometric authentication is now a standalone helper.
-
-**Before (1.2.x):**
-```kotlin
-// Biometrics tied to storage
-ksafe.put("key", value, useBiometrics = true)
-val data = ksafe.get("key", default, useBiometrics = true)
-```
-
-**After (1.3.0):**
-```kotlin
-// Biometrics as a separate verification step
-ksafe.verifyBiometricDirect("Authenticate to save") { success ->
-    if (success) {
-        ksafe.putDirect("key", value)
-    }
-}
-
-// Or with suspend function
-if (ksafe.verifyBiometric("Authenticate to read")) {
-    val data = ksafe.get("key", default)
-}
-
-// With duration caching (60 seconds, scoped to ViewModel)
-ksafe.verifyBiometricDirect(
-    reason = "Authenticate",
-    authorizationDuration = BiometricAuthorizationDuration(
-        duration = 60_000L,
-        scope = viewModelScope.hashCode().toString()
-    )
-) { success ->
-    if (success) { /* ... */ }
-}
-```
-
 ### From v1.1.x to v1.2.0+
 
 #### Binary Compatibility

ksafe/src/commonMain/kotlin/eu/anifantakis/lib/ksafe/KSafeConfig.kt

@@ -14,39 +14,42 @@ package eu.anifantakis.lib.ksafe
  *
  * // Custom key size
  * val ksafe128 = KSafe(context, config = KSafeConfig(keySize = 128))
- *
- * // Android: customize biometric auth validity duration
- * val androidSafe = KSafe(
- *     context,
- *     config = KSafeConfig(androidAuthValiditySeconds = 60)
- * )
  * ```
  *
- * ## Biometric Protection
+ * ## Biometric Authentication
  *
- * Biometric protection is configured **per-value**, not at the KSafe instance level:
+ * Biometric authentication is a **standalone helper** decoupled from storage operations.
+ * Use `verifyBiometric()` or `verifyBiometricDirect()` to protect any action:
  *
  * ```kotlin
  * val ksafe = KSafe(context)
  *
- * // Per-value biometric protection
- * var authToken by ksafe(defaultValue = "", encrypted = true, useBiometrics = true)  // 🔐 Protected
- * var theme by ksafe(defaultValue = "light", encrypted = false)  // Not protected
- * ```
+ * // Protect storage with biometrics
+ * ksafe.verifyBiometricDirect("Authenticate to save") { success ->
+ *     if (success) {
+ *         ksafe.putDirect("authToken", token)
+ *     }
+ * }
  *
- * Platform behavior when `useBiometrics = true`:
+ * // With duration caching (60 seconds, scoped to ViewModel)
+ * ksafe.verifyBiometricDirect(
+ *     reason = "Authenticate",
+ *     authorizationDuration = BiometricAuthorizationDuration(60_000L, viewModelScope.hashCode().toString())
+ * ) { success ->
+ *     if (success) { /* ... */ }
+ * }
+ * ```
  *
  * | Platform | Behavior |
  * |----------|----------|
- * | **Android** | Time-bound: Key usable for N seconds after BiometricPrompt/device unlock |
- * | **iOS** | Per-access: Face ID / Touch ID / Passcode prompt on each key access |
- * | **JVM** | Ignored (no biometric hardware available) |
+ * | **Android** | BiometricPrompt with fingerprint/face/device credential |
+ * | **iOS** | Face ID / Touch ID / Passcode via LocalAuthentication |
+ * | **JVM** | Always returns true (no biometric hardware available) |
  *
  * @property keySize The size of the AES key in bits. Supported values: 128, 256. Default is 256.
  *           **Note:** 128-bit keys may offer marginally faster encryption on very old devices,
  *           but 256-bit is strongly recommended for all modern devices (negligible performance difference).
- * @property androidAuthValiditySeconds **Android only.** Duration in seconds that biometric-protected
- *           keys remain usable after authentication. Default is 30 seconds. Ignored on iOS/JVM.
+ * @property androidAuthValiditySeconds Reserved for future use. Default is 30 seconds.
  */
 data class KSafeConfig(
     val keySize: Int = 256,

ksafe/src/commonTest/kotlin/eu/anifantakis/lib/ksafe/KSafeConfigTest.kt

@@ -8,8 +8,8 @@ import kotlin.test.assertFalse
 /**
  * Tests for [KSafeConfig] validation and defaults.
  *
- * Note: Biometric protection is now configured per-value (via `useBiometrics` parameter),
- * not at the KSafeConfig level. See KSafe API for biometric usage.
+ * Note: Biometric authentication is a standalone helper via `verifyBiometric()` and
+ * `verifyBiometricDirect()`. See KSafe API for biometric usage.
  */
 class KSafeConfigTest {