Ksafe

KSafe — Kotlin Multiplatform Encrypted Persistence

You are about to write or modify code that uses KSafe: a one-API encrypted key-value store covering Android, iOS, native macOS, JVM Desktop, Kotlin/WasmJS, and Kotlin/JS. Encrypted values use AES-GCM. Keep payload encryption, durable key custody, and the working key in process memory conceptually separate: the secure paths protect a long-lived key or KEK in a platform vault, while documented software fallbacks can keep key material in a permission-protected file. Use protectionInfo to report the route that was actually achieved.

This skill is self-contained — it covers everything you need to set up and use KSafe correctly. Always prefer the property delegate as the default API.

The single most important fact: KSafe is encrypted by default. ksafe(value) encrypts. You opt out for non-secret values with mode = KSafeWriteMode.Plain.

Key-custody matrix (this is what makes KSafe interesting)

When a stronger tier is absent (for example no StrongBox, no Secure Enclave, or no supported desktop OS vault), KSafe degrades to the documented next-best path and reports the degrade through KSafe.protectionInfo. If a real JVM OS vault exists but is temporarily unreachable, KSafe fails closed instead of inventing a replacement software key. Never trade operability for silent data loss.

SETUP

Dependencies

// commonMain (or Android-only) build.gradle.kts
implementation("eu.anifantakis:ksafe:<latest>")              // core
implementation("eu.anifantakis:ksafe-compose:<latest>")      // optional: Compose state
implementation("eu.anifantakis:ksafe-biometrics:<latest>")   // optional: biometric prompts

kotlinx-serialization-json comes transitively — don't add it yourself. If you store @Serializable classes, apply the kotlin-serialization plugin in your app.

Construction

// Android — pass applicationContext (NOT an Activity context — it leaks)
val ksafe = KSafe(applicationContext)

// iOS / macOS / JVM / WasmJS / JS — no context
val ksafe = KSafe()
val ksafe = KSafe(fileName = "auth")   // isolated named instance

Full factory parameters (all platforms except where noted):

KSafe(
    context: Context,                    // Android ONLY — applicationContext
    fileName: String? = null,            // null = default instance; else isolates storage
    lazyLoad: Boolean = false,           // ignored on web
    memoryPolicy: KSafeMemoryPolicy = KSafeMemoryPolicy.LAZY_PLAIN_TEXT,
    config: KSafeConfig = KSafeConfig(),
    securityPolicy: KSafeSecurityPolicy = KSafeSecurityPolicy.Default,
    baseDir: File? = null,               // JVM/Android custom dir; iOS uses `directory: String?`
)

KSafeConfig(
    aesKeySize: KSafeAesKeySize = KSafeAesKeySize.BITS_256, // BITS_128 or BITS_256; every platform
    requireUnlockedDevice: Boolean = false,  // default unlock policy for encrypted writes
    json: Json = KSafeDefaults.json,         // custom serialization
    appNamespace: String? = null,            // multi-app isolation (see below)
    keyRotationPolicy: KSafeKeyRotationPolicy = KSafeKeyRotationPolicy.Never,  // see Key rotation
    keyRotationRetryAttempts: Int = 3,       // next-instance retries for skipped work; 0 = off
)

Recommended DI setup (Koin) — mode-typed views over ONE instance (3.1.0+)

Encryption adds per-value overhead (AES-GCM + JSON envelope; ~µs since 2.1.2, but never free). For non-secret data — theme, last screen, UI flags — that overhead is wasted. Since 3.1.0 the recommended pattern is one store, typed views: KSafePlain / KSafeEncrypted / KSafeHardwareIsolated wrap an existing instance and freeze the write mode at the type level, so no call site carries a mode = argument the author can forget — and the compiler replaces the stringly named(...) qualifiers.

// commonMain
expect val platformModule: Module

// androidMain
actual val platformModule = module {
    single { KSafe(context = androidApplication(), fileName = "app") }
    single { KSafePlain(get()) }
    single { KSafeHardwareIsolated(get()) }
}

// iosMain / jvmMain / wasmJsMain / jsMain (no context)
actual val platformModule = module {
    single { KSafe(fileName = "app") }
    single { KSafePlain(get()) }
    single { KSafeHardwareIsolated(get()) }
}

class MyViewModel(
    private val prefs: KSafePlain,             // every write is Plain — by TYPE
    private val vault: KSafeHardwareIsolated,  // every write requests SE/StrongBox — by TYPE
) : ViewModel() {
    var theme      by prefs("dark")        // no mode argument exists to get wrong
    var lastScreen by prefs("home")

    var authToken  by vault("")
    var userPin    by vault("")
}

All views share the one store (same file, key namespace, cache — and ONE awaitCacheReady() on web). Rules an agent must know:

• The guarantee is write-side only: reads are mode-free and auto-detect each entry's protection, so prefs.get() reads an encrypted entry fine.
• The views cover the FULL write surface: put/putDirect, the by view(...) delegate (3.2.0+: its result is a KSafeReference, also a no-by .value handle when given an explicit key — see Direct handle under USAGE), asFlow/asWritableFlow/asStateFlow/asMutableStateFlow/getStateFlow, and (via :ksafe-compose) mutableStateOf/rememberKSafeState.
• Store-scoped operations (rotateKeys, clearAll, close, protectionInfo, getKeyInfo, awaitCacheReady, getOrCreateSecret) are NOT on the views — call them on view.ksafe.
• KSafeEncrypted(ksafe, requireUnlockedDevice = true) freezes a strict unlock policy for everything written through that view; the default constructor inherits KSafe.defaultWriteMode.
• Quick local views without DI: ksafe.plain / ksafe.encrypted / ksafe.hardwareIsolated.

Pre-3.1.0 (or when you genuinely want separate files): the older two-instance pattern with named("prefs") / named("vault") qualifiers and explicit mode = KSafeWriteMode.Plain per declaration still works — but it is convention, not a compiler guarantee.

If your app only stores secrets, a single default instance is fine:

actual val platformModule = module { single { KSafe(/* androidApplication() on Android */) } }

Multiple instances — the rules

• Each KSafe(fileName=...) should be a singleton. Create once (via DI), reuse everywhere.
• Two live instances on the same fileName are safe on Android / iOS / macOS / JVM: since 2.1.2 they share one ref-counted backend (only the last close() tears it down), since 3.0.0 a per-store commit lock serializes their commits, rotation and key sweeps, and since 3.2.0 they share one storage layer, so a write, clearAll() or rotateKeys() through one instance is seen by every other live instance on that file. Still wasteful, and still broken on web (per-instance caches diverge). Keep the singleton pattern.
• One process only. KSafe wires a single-process DataStore coordinator plus its own process-local cache/write queue. DataStore itself has multi-process APIs, but KSafe does not use them — never touch the same fileName from a second process (widget, foreground service, push process). Give other processes their own fileName.
• fileName must match [a-z][a-z0-9_]* — start lowercase, then lowercase/digits/underscores. Valid: "userdata", "settings", "data_v2". Invalid: spaces, dots, slashes, hyphens, uppercase.
• Key names: two reserved patterns are rejected on write (3.0.0+) with IllegalArgumentException: keys starting with __ksafe_ or encrypted_, and keys whose trailing segment — after a . or a :, the two ways the platforms join an alias — spells one of KSafe's alias sentinels: __ksafe_master__ / __ksafe_master_locked__ (optionally .gN), __ksafe_strict__ / __ksafe_gen__ (optionally .h<hex>), or the JVM vault markers __ksafe_nsdel__ / __ksafe_swfb__. Simple rule: never end a key with a __ksafe_…__ segment. Fail-fast on put/putDirect/delete/deleteDirect, delegate assignment, Compose state, and flow writes; reads are unaffected. "user_encrypted_flag" is fine — the prefix must match exactly.

// ✅ Good — singletons via DI
val appModule = module {
    single { KSafe() }                                  // default
    single(named("user")) { KSafe(fileName = "userdata") }
}
// ❌ Bad — two instances, same file
class ScreenA { val prefs = KSafe(fileName = "userdata") }
class ScreenB { val prefs = KSafe(fileName = "userdata") }   // DON'T

Custom storage directory (optional)

Defaults are platform-appropriate (Android app sandbox, iOS NSApplicationSupportDirectory, JVM ~/.eu_anifantakis_ksafe/ at 0700, web localStorage). Override only when needed:

// JVM — e.g. align with XDG
val ksafe = KSafe(fileName = "vault", baseDir = File("$xdgDataHome/myapp/ksafe"))

// Android — e.g. no-backup dir
val ksafe = KSafe(context = context, fileName = "vault", baseDir = File(context.noBackupFilesDir, "ksafe"))

// iOS — absolute path string (note: `directory`, not `baseDir`)
val ksafe = KSafe(fileName = "vault", directory = "/path/to/dir")

Web has no directory concept (no baseDir). Don't point baseDir at external storage for sensitive data on Android.

KSafe.close() — only when re-creating instances mid-process

The app-lifetime singleton never needs disposal (the OS reclaims everything at exit). close() exists for account/profile switching that changes fileName, long-running JVM services building per-session instances, or dev-time hot-reload. It cancels background coroutines and releases the DataStore scope/file handle — ref-counted since 2.1.2, so closing one instance never breaks another still using the same fileName. Idempotent; after close() discard the instance — suspend calls on a closed instance can suspend indefinitely rather than fail fast. Quiesce your own writers first: close() cancels the awaiters of writes already queued when it runs, but a suspending write racing close() from another coroutine can slip past that one-shot drain and never complete — await your in-flight writes before closing.

Web ONLY — awaitCacheReady()

WebCrypto is async-only, so on WasmJS/JS KSafe must finish decrypting its cache before the first synchronous read of an encrypted key. Call awaitCacheReady() once at startup. No-op on Android/iOS/macOS/JVM. Placement depends on how you start Koin:

// startKoin (classic) — Koin is up before ComposeViewport, getKoin() works immediately
fun main() {
    startKoin { modules(sharedModule, platformModule) }
    ComposeViewport(document.body!!) {
        var ready by remember { mutableStateOf(false) }
        LaunchedEffect(Unit) { getKoin().get<KSafe>().awaitCacheReady(); ready = true }
        if (ready) App()
    }
}

// KoinMultiplatformApplication (Compose) — awaitCacheReady must go INSIDE the composable
fun main() {
    ComposeViewport(document.body!!) {
        KoinMultiplatformApplication(config = createKoinConfiguration()) {
            var ready by remember { mutableStateOf(false) }
            LaunchedEffect(Unit) { getKoin().get<KSafe>().awaitCacheReady(); ready = true }
            if (ready) AppContent()
        }
    }
}

In a multiplatform app, awaitCacheReady() cannot be called from common code — the extension is declared only on web source sets. Wrap it in an expect/actual barrier so shared startup code awaits it with no platform guard (pass EVERY app-lifetime KSafe instance):

// commonMain
expect suspend fun awaitKSafeCachesReady(vararg stores: KSafe)

// webMain (or identical jsMain + wasmJsMain files if you have no webMain source set)
actual suspend fun awaitKSafeCachesReady(vararg stores: KSafe) {
    stores.forEach { it.awaitCacheReady() }
}

// androidMain / appleMain / jvmMain — reads are synchronous once the instance exists
actual suspend fun awaitKSafeCachesReady(vararg stores: KSafe) = Unit

USAGE

Property delegate — the 80% case (encrypted by default)

Default value is the first positional argument (there is no default = or encrypted = named parameter — encrypted is a deprecated legacy param, never generate it). Storage key defaults to the property name unless you pass key.

class AuthViewModel(private val ksafe: KSafe) : ViewModel() {
    var authToken by ksafe("")                                  // encrypted (default)
    var userId    by ksafe(0L, mode = KSafeWriteMode.Plain)     // opt OUT of encryption
    var lastSync  by ksafe(Instant.EPOCH)                       // any @Serializable type
    var theme     by ksafe(ThemeMode.DEVICE, key = "theme", mode = KSafeWriteMode.Plain)

    init { authToken = "..." }   // just assign — reads sync from hot cache, writes coalesce
}

What you get: synchronous reads from an in-memory hot cache (~µs), coalesced background writes (multiple writes within a 16ms window land in one transaction, never blocks the caller), and reactivity (see Flows below). The delegate works on any KSafe instance — var x by myKsafe(value) makes myKsafe the backing store.

Direct handle — ksafe(default, key) without by (3.2.0+)

The same call, given an explicit key, returns a KSafeReference<T> you can hold in a val, hand to a class, and read or write through .value. Reads come from the same hot cache as the delegate; writes are fire-and-forget with the KSafeWriteMode captured when the handle was created. The mode views' invoke returns the same handle with their frozen mode (ksafe.plain(0, key = "theme"), vault("", key = "pin")). Delegate and handle share one store and one cache — mix them freely.

class SessionRepository(ksafe: KSafe) {
    private val token    = ksafe("", key = "auth_token")       // KSafeReference<String>, encrypted
    private val launches = ksafe.plain(0, key = "launches")    // Plain, frozen by the view

    fun onLogin(t: String) { token.value = t; launches.value++ }
    fun isLoggedIn() = token.value.isNotEmpty()
}

Three rules:

• .value needs an explicit key. A plain = carries no property name, so a key-less handle is delegate-only and .value on it throws IllegalStateException.
• Never read .value inside a composable. No snapshot state sits behind the handle, so the composable will not recompose when the value changes. Use :ksafe-compose (rememberKSafeState / mutableStateOf) or asStateFlow().collectAsState() instead.
• The deprecated encrypted: Boolean overload still returns the delegate type. Never generate it (see above); if you meet one, move it to mode before using .value.

Storing complex objects

@Serializable
data class AuthInfo(val accessToken: String = "", val refreshToken: String = "", val expiresIn: Long = 0L)

var authInfo by ksafe(AuthInfo())            // encryption + JSON automatically
authInfo = authInfo.copy(accessToken = "newToken")

"Serializer for class X is not found"? Add @Serializable and the serialization plugin.

Nullable values — the reified-null trap (IMPORTANT)

KSafe supports nullable types, and null is preserved as a distinct state (not "missing"). But never pass a bare null as the default value — reified generics have nothing to infer T from, so T collapses to Nothing? and the call always returns null even when a value is stored.

// ❌ Wrong — always returns null, ignores stored value
val token = ksafe.get("auth_token", null)
var token by ksafe(null)

// ✅ Correct — explicit type parameter
val token = ksafe.get<String?>("auth_token", null)
var token by ksafe<String?>(null)

// ✅ Correct — typed declaration drives inference
val token: String? = ksafe.get("auth_token", null)
var token: String? by ksafe(null)

Suspend vs Direct API

// Suspend — awaits the disk commit. Use when persistence is a precondition
// for the next step (token refresh, payment confirmation). Concurrent callers
// get coalesced, so individual latency drops under load.
suspend fun save() {
    ksafe.put("profile", userProfile)
    val cached: User = ksafe.get("profile", User())
}

// Direct — fire-and-forget (queue + return). Use for UI/hot-cache writes where
// you don't need to know the disk write landed.
ksafe.putDirect("counter", 42)
val n = ksafe.getDirect("counter", 0)

Signature order is key first, then defaultValue: get(key, defaultValue), getDirect(key, defaultValue).

Repository data source — KSafe behind your own interface (3.3.0+)

When you create a repository or a local data source that persists values with KSafe, propose this shape by default: the repository depends on one small app-owned interface, not on KSafe. One interface serves every repository, one KSafe-backed class implements it, and one map-backed fake replaces it in plain commonTest unit tests (no device, no Keystore, no Android Context).

It rests on the explicit-serializer overloads (3.3.0+): every typed call (get, getDirect, getFlow, getStateFlow, put, putDirect) also takes a KSerializer<T> right after the value. The reified calls cannot be used here — a generic interface method has no reified T ("Cannot use 'T' as reified type parameter").

// Data layer: the only storage type repositories see.
interface SecureStore {
    suspend fun <T> get(key: String, defaultValue: T, serializer: KSerializer<T>): T
    suspend fun <T> put(key: String, value: T, serializer: KSerializer<T>)
    fun <T> observe(key: String, defaultValue: T, serializer: KSerializer<T>): Flow<T>
    suspend fun delete(key: String)
}

// Short call sites: store.get("theme", "light"), store.put("ids", ids), store.observe("info", Info()).
suspend inline fun <reified T> SecureStore.get(key: String, defaultValue: T): T = get(key, defaultValue, serializer())
suspend inline fun <reified T> SecureStore.put(key: String, value: T) = put(key, value, serializer())
inline fun <reified T> SecureStore.observe(key: String, defaultValue: T): Flow<T> = observe(key, defaultValue, serializer())

// Production: the only class that touches KSafe. The write mode is fixed per instance.
class KSafeSecureStore(
    private val ksafe: KSafe,
    private val mode: KSafeWriteMode = ksafe.defaultWriteMode,
) : SecureStore {
    override suspend fun <T> get(key: String, defaultValue: T, serializer: KSerializer<T>): T =
        ksafe.get(key, defaultValue, serializer)
    override suspend fun <T> put(key: String, value: T, serializer: KSerializer<T>) =
        ksafe.put(key, value, serializer, mode)
    override fun <T> observe(key: String, defaultValue: T, serializer: KSerializer<T>): Flow<T> =
        ksafe.getFlow(key, defaultValue, serializer)
    override suspend fun delete(key: String) = ksafe.delete(key)
}

// commonTest: one fake for every repository.
class FakeSecureStore : SecureStore {
    private val values = MutableStateFlow<Map<String, Any?>>(emptyMap())
    @Suppress("UNCHECKED_CAST")
    override suspend fun <T> get(key: String, defaultValue: T, serializer: KSerializer<T>): T =
        if (key in values.value) values.value[key] as T else defaultValue
    override suspend fun <T> put(key: String, value: T, serializer: KSerializer<T>) =
        values.update { it + (key to value) }
    @Suppress("UNCHECKED_CAST")
    override fun <T> observe(key: String, defaultValue: T, serializer: KSerializer<T>): Flow<T> =
        values.map { if (key in it) it[key] as T else defaultValue }.distinctUntilChanged()
    override suspend fun delete(key: String) = values.update { it - key }
}

// A repository depends on the interface only.
class AuthRepository(private val store: SecureStore) {
    suspend fun accessToken(): String? = store.get<String?>("access_token", null)
    suspend fun saveAccessToken(token: String?) = store.put("access_token", token)
    val authInfo: Flow<AuthInfo> = store.observe("auth_info", AuthInfo())
}

// Koin: one store per sensitivity, still one KSafe file.
single<SecureStore> { KSafeSecureStore(get()) }                                        // encrypted
single<SecureStore>(named("prefs")) { KSafeSecureStore(get(), KSafeWriteMode.Plain) }  // non-secret

Rules for this pattern:

• A non-suspend interface (fun <T> get(...)) is implemented with getDirect / putDirect; a suspend one with get / put.
• There is no KClass overload. Pass a KSerializer: User.serializer(), ListSerializer(User.serializer()), or serializer<T>() inside a reified function.
• A nullable T needs a nullable serializer (String.serializer().nullable); the reified extension builds it when the type is String?. The serializer, not the default, decides whether a stored null reads back as null.
• Both forms share one store: an entry written with a serializer reads back through the reified calls, and the other way round.
• Mode views and delegates have no serializer overload. Fix the write mode in the store instance (the mode parameter above) instead.
• A feature-specific data source with concrete types (reified calls inside its implementation) also works and needs no serializer. Prefer the shared SecureStore once more than one repository persists data: one fake then covers all of them.

Write modes

The delegate / mutableStateOf / put all default to encrypted. Use mode for control. The protection param of KSafeWriteMode.Encrypted is KSafeEncryptedProtection (write-side), NOT KSafeProtection (the read-side enum from getKeyInfo). Using KSafeProtection here will not compile.

// Per-entry unlock policy (Apple) — inaccessible until first unlock since boot
ksafe.put("token", value, mode = KSafeWriteMode.Encrypted(
    protection = KSafeEncryptedProtection.DEFAULT,
    requireUnlockedDevice = true,
))

// HARDWARE_ISOLATED — StrongBox (Android) / Secure Enclave (Apple). Slower,
// per-key Keystore allocation, needs hardware. Reserve for master passphrases /
// identity keys; do NOT use as a default.
ksafe.put("master_passphrase", value, mode = KSafeWriteMode.Encrypted(
    protection = KSafeEncryptedProtection.HARDWARE_ISOLATED,
))

// Explicit plaintext
ksafe.putDirect("theme", "dark", mode = KSafeWriteMode.Plain)

No-mode writes use encrypted defaults and pick up KSafeConfig.requireUnlockedDevice.

Tightening an existing HARDWARE_ISOLATED entry's unlock policy (rewriting it with requireUnlockedDevice = true over a relaxed entry) takes effect at that write (3.0.0+), and it is copy-on-write: Android mints the strict Keystore key under a fresh internal alias and the relaxed key is reclaimed only after the rewrite commits — a locked device, a Keystore outage, or a crash mid-tighten just fails the write (retry later); the previous value stays readable. On Apple a tighten that can't be applied fails the write instead of leaving the item looser than declared — prefer suspend put for a policy tighten so a failure surfaces. Loosening back to relaxed is best-effort and never fails a write.

Deleting

ksafe.delete("profile")        // suspend
ksafe.deleteDirect("profile")  // fire-and-forget
ksafe.clearAll()               // suspend — wipes everything (data + keys). Destructive.

Deleting removes both the value and its encryption key.

Reactive reads — Flows and StateFlows

All four are property delegates with defaultValue first. All auto-update on writes from anywhere (another screen, background sync, another delegate on the same key). asFlow / asStateFlow are read-only (writes go through put/putDirect); asWritableFlow / asMutableStateFlow are writable.

The explicit-key twins are getFlow(key, default) (cold) and getStateFlow(key, default, scope) (hot); there are no writable twins, since writes go through put/putDirect anyway. Same types, but only the delegates cache: every getStateFlow call starts another watcher — see ANTI-patterns.

class Repo(private val ksafe: KSafe) {
    // Cold Flow<T> — read-only. Encrypted by default; pass mode = Plain to opt out.
    val username: Flow<String> by ksafe.asFlow("Guest")
    val theme: Flow<String> by ksafe.asFlow("light", key = "app_theme")

    // Writable cold Flow<T> — set() persists, no CoroutineScope needed.
    val themeMode: WritableKSafeFlow<ThemeMode> by ksafe.asWritableFlow(ThemeMode.DEVICE)
    fun setTheme(m: ThemeMode) = themeMode.set(m)
}

class VM(private val ksafe: KSafe) : ViewModel() {
    // Hot StateFlow<T> — read-only. Needs a scope.
    val username: StateFlow<String> by ksafe.asStateFlow("Guest", viewModelScope)

    // Hot MutableStateFlow<T> — .value = / .update {} persist automatically.
    // Drop-in for the standard MutableStateFlow pattern, but persisted + reactive.
    // Once you write through it, your value wins over stale storage echoes (2.1.2+).
    private val _state by ksafe.asMutableStateFlow(MoviesState(), viewModelScope)
    val state = _state.asStateFlow()

    fun load() { _state.update { it.copy(loading = true) } }
}

// Direct (non-delegate) form also exists:
ksafe.getFlow(key, defaultValue).collect { … }

Or collect a delegate's flow in Compose: val name by repo.username.collectAsState().

Compose state — :ksafe-compose

Two APIs with deliberately different default modes:

// mutableStateOf — ENCRYPTED by default. For class fields (ViewModel/repository):
// created once, lives for the class lifetime.
class CounterViewModel(private val ksafe: KSafe) : ViewModel() {
    var pin by ksafe.mutableStateOf("")                          // encrypted (default)
    var counter by ksafe.mutableStateOf(0, mode = KSafeWriteMode.Plain)  // opt out

    // Optional `scope` = live cross-screen sync (auto-updates when ANY writer changes
    // the key). Without scope: reads once at init, writes persist, but no live sync.
    // Since 2.1.2: once you write THROUGH a live state, your value is authoritative —
    // external emissions no longer revert in-flight edits (a pure-observer state the
    // user never writes still live-updates as before).
    var username by ksafe.mutableStateOf("Guest", scope = viewModelScope)
}

// rememberKSafeState — PLAIN by default (UI ephemera rarely needs encryption).
// For composable-BODY state (no ViewModel). It's an EXTENSION on ksafe, default value
// first. remember-scoped, so it survives recomposition AND process death.
@Composable
fun TabbedScreen(ksafe: KSafe) {
    var currentTab by ksafe.rememberKSafeState(0)                       // key = "currentTab"
    var draft by ksafe.rememberKSafeState("", key = "screen.draft")     // explicit key
    var pin by ksafe.rememberKSafeState("", mode = KSafeWriteMode.Encrypted())  // opt IN

    // Live cross-screen sync:
    var theme by ksafe.rememberKSafeState(ThemeMode.LIGHT, key = "theme", observeExternalChanges = true)
}

Rule of thumb: ViewModel/class property → mutableStateOf. Composable-body local state (tab index, scroll position, draft text, expanded sections) → rememberKSafeState. Domain data shared across screens stays in a ViewModel with mutableStateOf.

Memory policy (construction-time tuning)

KSafe(memoryPolicy = …) controls how the in-RAM cache holds values. Default is LAZY_PLAIN_TEXT — leave it unless you have a specific reason.

Since 2.1.2, ENCRYPTED reads are pure-CPU AES on every platform (~µs): Android uses a TEE-wrapped data-encryption key unwrapped once into memory, matching what Apple/JVM always did. ENCRYPTED is now a realistic default for security-sensitive apps, not a 100× Android penalty. (HARDWARE_ISOLATED entries and a requireUnlockedDevice master still decrypt inside the TEE on every op — that's the point of those tiers.)

Web forces PLAIN_TEXT internally (WebCrypto async-only) — hence awaitCacheReady().

Biometric-gated actions — :ksafe-biometrics (independent, static API)

Independent of :ksafe — call directly for any biometric prompt. No DI, no Context, no init. Android auto-inits via ContentProvider (no Application changes); requires AppCompatActivity.

// Callback variant — works anywhere
KSafeBiometrics.verifyBiometricDirect("Unlock balance") { success -> if (success) showBalance() }

// Suspend variant
viewModelScope.launch {
    if (KSafeBiometrics.verifyBiometric("Confirm transaction")) proceed()
}

// Avoid re-prompts within a window. duration MUST be > 0 — a duration <= 0 is the
// opt-out and never caches (enforced since 2.1.2). scope = null is the global session,
// distinct from every named scope (including ""). The window counts real elapsed time,
// including device sleep.
KSafeBiometrics.verifyBiometric(
    reason = "Reauth",
    authorizationDuration = BiometricAuthorizationDuration(duration = 60_000L, scope = "MyScope"),
)

// Hard biometric-only (no PIN/password/Apple-Watch fallback)
KSafeBiometrics.verifyBiometric("Step-up", allowDeviceCredentialFallback = false)

Know up front whether a real prompt is even possible (2.2.1+) — false means verify would pass through / refuse without gating, so route to your own PIN/password flow instead:

// suspend — never shows UI, no gesture needed. Probe ONCE at startup (on web: next to
// awaitCacheReady()) and keep the result in app state for synchronous `if (available)` use.
// On Android probe from a composition/Activity, NOT Application.onCreate — no FragmentActivity
// host exists that early, so the cached answer is a permanent false. verifyBiometric waits for
// the host; this probe does not.
if (KSafeBiometrics.biometricsAvailable()) { /* biometric flow */ } else { /* PIN screen */ }

// callback twin (non-suspending) — for a non-coroutine call site
KSafeBiometrics.biometricsAvailableDirect { available -> if (available) showUnlock() else showPin() }

verifyBiometric is suspend; verifyBiometricDirect is callback-based and delivers onResult on the main thread on Android and Apple (2.1.2+) — safe to touch UI from it. Concurrent calls are serialized on every platform (Apple since 3.1.0): a second prompt queues behind the first and skips entirely if the holder just authorized the same scope. Sequential calls never prompt twice inside the window regardless. On Android a queued caller whose host Activity stopped while it waited (e.g. a Home press) returns false instead of hanging (3.2.0+). Prompt text comes from three process-wide defaults set once at startup, with per-call overrides (title/cancelLabel are appended AFTER the existing params):

KSafeBiometrics.defaultTitle = "My App"        // Android prompt title + WEB PASSKEY NAME
KSafeBiometrics.defaultReason = "Unlock to continue"   // Android subtitle / Apple localizedReason / Hello message
KSafeBiometrics.defaultCancelLabel = null      // null = the platform's LOCALIZED default — leave it null

title names the web passkey (rp.name/user.name/displayName) and is written once at registration — set it before the first verifyBiometric(). Apple/JVM have no title, ignore it. Renaming later: re-enroll ONCE via the introspection, never unconditionally — if (KSafeBiometricsWeb.isRegistered && KSafeBiometricsWeb.registeredTitle != KSafeBiometrics.defaultTitle) KSafeBiometricsWeb.resetRegistration() (both reflect KSafe's local record, not the authenticator's real state).

clearBiometricAuth(scope = null) invalidates the cached authorization — all scopes, or one named scope — so the next gated action re-prompts; call it on logout / app-lock. It also revokes a prompt already on screen (3.0.0+): that caller still gets its true, but the success no longer seeds the prompt-free window.

Where a real prompt shows vs. pass-through — verifyBiometric does NOT gate on every platform:

Opt-outs restore the legacy always-true no-op: -Dksafe.biometrics.jvm.prompts=off (JVM desktop), KSafeBiometricsWeb.promptsEnabled = false (web). Web specifics: first successful call enrolls a passkey (that ceremony verifies the user); the reason string is NOT shown (browser-controlled dialog); call from a user gesture or the browser may reject; needs a secure context (HTTPS/localhost); KSafeBiometricsWeb.resetRegistration() re-enrolls after an OS-side passkey removal (3.0.0+: also revokes every cached auth window, so the next call is a fresh ceremony, never a cache hit). Footguns: (1) on Windows — and on the web where the platform treats the PIN as part of Hello — allowDeviceCredentialFallback = false can't exclude the PIN; it still keys the auth cache strictly. (2) JVM Linux always returns true (no prompt API) — never rely on verifyBiometric as your ONLY security boundary there; gate it yourself.

Database passphrase

getOrCreateSecret is a suspend extension — call from a coroutine.

suspend fun openDatabase(): AppDatabase {
    val passphrase: ByteArray = ksafe.getOrCreateSecret("main.db")   // 256-bit, hw-isolated, idempotent
    return Room.databaseBuilder(context, AppDatabase::class.java, "main.db")
        .openHelperFactory(SupportFactory(passphrase))
        .build()
}

Params: getOrCreateSecret(key, size = 32, protection = KSafeEncryptedProtection.HARDWARE_ISOLATED, requireUnlockedDevice = false). Works the same for SQLDelight + SQLCipher.

It never silently rotates. If a secret exists on disk but can't be decrypted right now (locked device at cold start, OS key vault momentarily unreachable), it throws instead of minting a replacement — a rotated secret would permanently orphan the database it keys. Catch and retry after unlock; don't catch-and-regenerate yourself.

Key rotation (3.0.0+)

Re-encrypt every encrypted entry under fresh key material — values never change, nothing migrates, works on every platform:

val r = ksafe.rotateKeys()   // suspend; KSafeRotationResult(rotated, skipped, failed, keyGeneration)

Or declaratively (checked once per startup, runs in the background, never blocks):

KSafe(config = KSafeConfig(keyRotationPolicy = KSafeKeyRotationPolicy.MaxAge(90.days)))

Rules an agent must know:

• Whole-store, not per-key. rotateKeys() re-keys the ENTIRE store — there is no per-key rotate overload (the DEFAULT tier shares one master key per store), so re-keying one value means rotating everything.

• Needs an operational backend. Rotation mints a new key generation, so it only works where protectionInfo.isEncryptionOperational is true; on a non-secure web page or a JVM whose OS vault is unreachable there is no fresh key to rotate to (entries come back skipped / failed). Preflight if unsure.

• Default is Never — no NEW generation starts unless the app opts in. Recommend MaxAge only for compliance-type asks (PCI/SOC2 "rotate data-at-rest keys"); keys don't expire otherwise. Since 3.1.0, Never does not disable recovery: a generation carrying the explicit r:1 lifecycle state resumes automatically on the next KSafe instance, and normally skipped work marked with a bounded rp:N budget retries at the same generation, at most once per next instance (3 attempts by default; 0 disables).

• MaxAge age clock: measured from the last rotation, or — for a never-rotated store — from the first launch under the policy (the birth is stamped then). So adding MaxAge to an existing store does NOT rotate it immediately; a pre-existing install doesn't retroactively count as old. Each rotation restarts the clock.

• Rotation also switches on the authenticated v3 envelope: after the first rotateKeys(), each ciphertext's AES-GCM AAD binds it to its identity + protection + unlock policy + generation, so a file-access attacker can't relocate a ciphertext or tamper its metadata and have it decrypt (reads fail closed). An un-rotated store's existing entries keep pre-3.0.0 bytes (new/rewritten strict HARDWARE_ISOLATED entries are the exception — they key under the 3.0.0 strict alias variant even at generation 1). Tell users who fear on-disk tampering to rotate once. AAD binds placement, NOT existence — it doesn't detect deletion or same-slot rollback (needs an external signed manifest). Rotation also upgrades any entries still on the legacy pre-2.x envelope to the current format as a free side effect (relevant for stores upgraded from very old KSafe versions).

• Erasure honesty: deleteKey/clearAll = cryptographic erasure (destroy the key → ciphertext is dead), NOT guaranteed physical byte-shredding. clearAll() empties the store via its API; it deliberately does not unlink the live file (that races writes). Hardware stores (Keystore/Keychain) give strong key erasure; the JVM software-fallback key file and web IndexedDB do not. Per platform:

  Platform	Where the key lives	What delete does	Erasure strength
  Android	Keystore/StrongBox (TEE/SE) + a wrapped software DEK in the store	KeyStore.deleteEntry + DEK-record removal	Strong — the secure element destroys the key
  iOS / macOS	Keychain (Secure Enclave for HARDWARE_ISOLATED)	SecItemDelete	Strong — SE keys are destroyed in hardware
  JVM Desktop	OS vault (DPAPI / login Keychain / libsecret), or a software fallback file	vault delete, or file overwrite	Strong with a vault; the fallback is a plaintext key file with no secure-erase guarantee
  Web	Non-extractable CryptoKey in IndexedDB	IDBObjectStore.delete	Medium — the key was never plaintext to JS, but browser storage reclamation is not a secure wipe

  Ciphertext bytes are a separate matter: clearAll() empties the store through its normal API and deliberately does NOT unlink or shred the live file (that races concurrent writes), so a journaling filesystem, an SSD's wear-levelling, or a backup snapshot may retain remnants no userspace library can reach. The guarantee KSafe actually makes is cryptographic erasure (NIST SP 800-88 "Cryptographic Erase"): destroy the key and the ciphertext is unrecoverable regardless of surviving bytes. Rotation strengthens it — after rotateKeys() the superseded master for every entry that was re-encrypted is deleted, so that generation's ciphertext is cryptographically dead. A superseded master is kept while ANY entry still references it, so skipped/failed entries keep their old key alive until a later pass supersedes them too.

• Crash-safe with automatic same-generation resume (3.1.0+): the generation bump and an "r":1 lifecycle marker are persisted before entries move. Each entry records the generation that decrypts it, so an interrupted pass leaves a readable mixed-generation store. The next KSafe instance resumes that SAME generation (also under Never), repeats the idempotent remainder, and changes the state to "r":0 only after the master sweep. This is one lifecycle field, not a per-entry journal/rollback log.

• Normally skipped work has a bounded persisted next-instance budget (3.1.0+): a pass that returns normally writes r:0; when it has skipped entries it also writes rp:N, where N = KSafeConfig.keyRotationRetryAttempts (default 3; set 0 to disable). This is not a timestamp and starts no timer: the current KSafe instance does not try again. Each next instance consumes at most one attempt and atomically claims r:0,rp:N -> r:1,rp:N-1 before retrying the SAME generation — no new key and no ts reset — including under Never. The decrement is durable, so a crash cannot refill the budget; r:1,rp:0 resumes the final claimed attempt but cannot arm another. If MaxAge is already due, its fresh-generation rotation takes precedence. failed alone never arms automatic retry: it means a definitive problem (e.g. key gone/ciphertext corrupt), so do not promise that the entry is readable.

• 3.0.0 compatibility guard: released 3.0.0 key-generation records have no r field. Absence is treated as an old completed record, never as proof of a crash. On the first 3.1.0 startup KSafe adds r:0, preserves generation/timestamp, and does no resume, generation bump, entry rewrite, key sweep, or same-launch MaxAge. Normal policy runs from the next launch. If 3.0.0 really left a mixed-generation store, its entries remain readable and a later manual/due rotation moves them normally. Unknown r values are preserved and rejected fail-closed.

• Observability: a background MaxAge pass logs KSafe: MaxAge key-rotation pass -> generation N (rotated X, skipped Y, failed Z). on success; crash recovery logs KSafe: resumed interrupted key rotation at generation N (rotated X, skipped Y, failed Z).; normal partial retry logs KSafe: retried incomplete key rotation at generation N (rotated X, skipped Y, failed Z). A failure logs scheduled key rotation failed … will retry on a later launch (console.warn on web). A manual rotateKeys() returns the same counts in its KSafeRotationResult; per-entry, read getKeyInfo(key)?.keyGeneration.

• getOrCreateSecret values are untouched (only their envelope re-wraps) — rotation never breaks a SQLCipher database.

• Downgrade footgun — treat rotation (and any 3.0.0 strict write) as a one-way door: a pre-3.0.0 binary can't resolve rotated or strict-variant keys, and its startup orphan sweep PERMANENTLY DELETES the rows it can't decrypt (typically on first launch). Upgrading back restores access only if that sweep never ran — back up before any planned downgrade.

• Per-entry check: ksafe.getKeyInfo(key)?.keyGeneration (1 = never rotated).

• Cost = one decrypt + one encrypt per entry (Keystore IPC-bound on Android) — call from a background coroutine on large stores. A second concurrent call on the same instance throws, but the guard is per-instance — still trigger rotation from ONE place. Two same-process instances rotating one fileName can't corrupt anything (the 3.0.0 per-store commit lock serializes commits, the rotation CAS, and key sweeps) but duplicate the work and can report spurious skipped/failed counts; a second PROCESS has no coordination at all and can genuinely race the superseded-key sweep (same-file multi-process is unsupported anyway).