
ksafe
KSafe — Kotlin Multiplatform encrypted persistence: patterns, anti-patterns, and gotchas for AI agents
- GitHub stars
- 346
Install
/plugin install ksafe@ksafeRun it inside Claude Code after adding the marketplace with /plugin marketplace add ioannisa/KSafe.
Contents
Discovered from sourceSkills 1
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)
| Platform | Default encrypted route | HARDWARE_ISOLATED upgrade / fallback |
|---|---|---|
| Android | Relaxed: non-exportable Keystore KEK wraps a DEK stored as ciphertext; the unwrapped DEK is cached in RAM. Strict unlock mode performs payload operations in Keystore. | Per-entry StrongBox when available; normal Keystore fallback otherwise. |
| iOS / native macOS | AES key stored in Keychain, loaded into the app for CryptoKit payload operations. | Secure Enclave EC key wraps a per-entry AES DEK; ordinary Keychain fallback otherwise. Simulator-only entitlement failure can use a reported software file fallback. |
| JVM Desktop | AES key protected by Windows DPAPI, macOS login Keychain, or Linux Secret Service, then loaded for JCE payload operations. | No stronger common tier. A reported permission-protected file fallback is used only where no usable OS vault exists or the user explicitly opts out. |
| WasmJS / JS | Non-extractable WebCrypto AES CryptoKey in IndexedDB. | No stronger tier; outside a secure context encrypted operations are non-operational rather than silently written plain. |
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, theby view(...)delegate (3.2.0+: its result is aKSafeReference, also a no-by.valuehandle 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 onview.ksafe. KSafeEncrypted(ksafe, requireUnlockedDevice = true)freezes a strict unlock policy for everything written through that view; the default constructor inheritsKSafe.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
fileNameare safe on Android / iOS / macOS / JVM: since 2.1.2 they share one ref-counted backend (only the lastclose()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()orrotateKeys()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
fileNamefrom a second process (widget, foreground service, push process). Give other processes their ownfileName. fileNamemust 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_orencrypted_, 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 onput/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:
.valueneeds an explicitkey. A plain=carries no property name, so a key-less handle is delegate-only and.valueon it throwsIllegalStateException.- Never read
.valueinside a composable. No snapshot state sits behind the handle, so the composable will not recompose when the value changes. Use:ksafe-compose(rememberKSafeState/mutableStateOf) orasStateFlow().collectAsState()instead. - The deprecated
encrypted: Booleanoverload still returns the delegate type. Never generate it (see above); if you meet one, move it tomodebefore 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 withgetDirect/putDirect; a suspend one withget/put. - There is no
KClassoverload. Pass aKSerializer:User.serializer(),ListSerializer(User.serializer()), orserializer<T>()inside a reified function. - A nullable
Tneeds a nullable serializer (String.serializer().nullable); the reified extension builds it when the type isString?. The serializer, not the default, decides whether a storednullreads back asnull. - 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
modeparameter above) instead. - A feature-specific data source with concrete types (reified calls inside its implementation)
also works and needs no serializer. Prefer the shared
SecureStoreonce 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.
| Policy | Behaviour |
|---|---|
LAZY_PLAIN_TEXT (default) | First read of a key decrypts on demand, then caches plaintext permanently. Cold start does no bulk decrypt; steady-state reads are O(1). Best general choice. |
ENCRYPTED | Ciphertext stays in RAM; every read decrypts. Lowest plaintext-in-RAM exposure. |
ENCRYPTED_WITH_TIMED_CACHE | Like ENCRYPTED, but decrypted plaintext is side-cached for a TTL window. |
PLAIN_TEXT | Eagerly decrypts everything at startup. Discouraged — pays full cold-start cost; same RAM exposure as LAZY_PLAIN_TEXT without the lazy benefit. |
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:
| Platform | Real prompt | Biometrics unavailable |
|---|---|---|
| Android | BiometricPrompt | false |
| iOS / native macOS | LAContext | false |
| JVM macOS (2.2.1+) | LocalAuthentication (policy maps like native macOS) | strict + no Touch ID, or the bridge fails to load → false |
| JVM Windows (2.2.1+) | Windows Hello (UserConsentVerifier) | strict + Hello not-configured, or the bridge fails to load → false |
| JS / WasmJS (2.2.1+) | WebAuthn platform authenticator (Touch ID / Hello / fingerprint) | permissive true / strict false |
| JVM Linux | none (no portable API) | always true (pass-through) |
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 (theDEFAULTtier 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.isEncryptionOperationalistrue; on a non-secure web page or a JVM whose OS vault is unreachable there is no fresh key to rotate to (entries come backskipped/failed). Preflight if unsure. -
Default is
Never— no NEW generation starts unless the app opts in. RecommendMaxAgeonly for compliance-type asks (PCI/SOC2 "rotate data-at-rest keys"); keys don't expire otherwise. Since 3.1.0,Neverdoes not disable recovery: a generation carrying the explicitr:1lifecycle state resumes automatically on the next KSafe instance, and normally skipped work marked with a boundedrp:Nbudget retries at the same generation, at most once per next instance (3 attempts by default; 0 disables). -
MaxAgeage 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 addingMaxAgeto 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 strictHARDWARE_ISOLATEDentries 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 removalStrong — the secure element destroys the key iOS / macOS Keychain (Secure Enclave for HARDWARE_ISOLATED)SecItemDeleteStrong — 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 CryptoKeyin IndexedDBIDBObjectStore.deleteMedium — 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 — afterrotateKeys()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":1lifecycle 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 underNever), repeats the idempotent remainder, and changes the state to"r":0only 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 hasskippedentries it also writesrp:N, whereN = 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 claimsr:0,rp:N -> r:1,rp:N-1before retrying the SAME generation — no new key and notsreset — including underNever. The decrement is durable, so a crash cannot refill the budget;r:1,rp:0resumes the final claimed attempt but cannot arm another. IfMaxAgeis already due, its fresh-generation rotation takes precedence.failedalone 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
rfield. Absence is treated as an old completed record, never as proof of a crash. On the first 3.1.0 startup KSafe addsr:0, preserves generation/timestamp, and does no resume, generation bump, entry rewrite, key sweep, or same-launchMaxAge. 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. Unknownrvalues are preserved and rejected fail-closed. -
Observability: a background
MaxAgepass logsKSafe: MaxAge key-rotation pass -> generation N (rotated X, skipped Y, failed Z).on success; crash recovery logsKSafe: resumed interrupted key rotation at generation N (rotated X, skipped Y, failed Z).; normal partial retry logsKSafe: retried incomplete key rotation at generation N (rotated X, skipped Y, failed Z).A failure logsscheduled key rotation failed … will retry on a later launch(console.warnon web). A manualrotateKeys()returns the same counts in itsKSafeRotationResult; per-entry, readgetKeyInfo(key)?.keyGeneration. -
getOrCreateSecretvalues 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
fileNamecan'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 spuriousskipped/failedcounts; a second PROCESS has no coordination at all and can genuinely race the superseded-key sweep (same-file multi-process is unsupported anyway).
Custom serialization
val json = Json {
serializersModule = SerializersModule {
contextual(UUID::class, UUIDSerializer)
contextual(Instant::class, InstantSerializer)
}
}
val ksafe = KSafe(config = KSafeConfig(json = json))
@Serializable
data class User(@Contextual val id: UUID, val name: String)
Diagnostics — KSafe.protectionInfo and KSafe.VERSION
val info = ksafe.protectionInfo // recomputed per access (2.1.1+): a runtime JVM degrade shows up live
// 3.2.0+: on Android with a secure lock screen (API 35+ included) this does
// ONE blocking store read per process (again after clearAll()) — call it
// off the main thread, never in Activity.onCreate
check(info.effectiveLevel >= KSafeProtectionLevel.SANDBOX_PROTECTED) {
"Need sandbox-grade key protection; got ${info.custody}"
}
check(info.effectiveLevel >= info.intendedLevel) // STRENGTH: detect silent fallback (posture gate)
// OPERABILITY (3.0.0+): "will encrypted writes actually SUCCEED?" — cross-platform, no platform code.
// Different question from strength: a JVM / iOS-Simulator software fallback is weaker but WORKS, so
// this stays true there. It's false only where encrypted ops genuinely can't run — today two cases:
// a web page outside a secure context (no crypto.subtle), and a JVM whose OS vault EXISTS but failed
// its construction self-test (locked keychain/keyring — "jvm_os_vault_degraded"; the no-vault-at-all
// software fallback stays operational). Gate a login / first write on it.
if (!info.isEncryptionOperational) error("KSafe: encryption unavailable — web: serve over HTTPS/localhost; JVM: unlock the OS keyring (or -Dksafe.jvm.keyVault=software)")
analytics.log("ksafe_protection",
"level" to info.effectiveLevel.name, // SOFTWARE | SANDBOX_PROTECTED | HARDWARE_BACKED | HARDWARE_ISOLATED
"custody" to info.custody, // human-readable, never parse
"notes" to info.notes.joinToString(","),// stable lowercase_snake codes
"version" to info.kSafeVersion) // == KSafe.VERSION
Two distinct questions, two gates — don't conflate them: effectiveLevel (vs intendedLevel)
answers "how strong?" — a weaker-but-working fallback still trips != intendedLevel, so it's a
posture/compliance bar. isEncryptionOperational answers "does it work at all?" — use it to gate
a login or first encrypted write. Gating operability on the level inequality would wrongly block
every iOS-Simulator run and every headless desktop without an OS keyring.
Per-key audit: ksafe.getKeyInfo(key) → KSafeKeyInfo(protection, storage, level, keyGeneration);
prefer .level (same scale as protectionInfo; on web it also reports the non-secure-context
degrade). On Apple (3.0.0+) .level reports the live Keychain custody of the entry's actual key —
a HARDWARE_ISOLATED request served by a legacy plain key reads HARDWARE_BACKED, the
iOS-Simulator file fallback reads SOFTWARE — a real audit of what each entry got, not an echo of
the request. Android infers from the requested tier plus StrongBox capability, so a per-key silent
downgrade is only detectable on Apple. Device capability probe: ksafe.deviceKeyStorages.
⚠️ Compose Desktop release distributables — strongly recommend modules("jdk.unsupported")
For any production Compose Desktop release build, add these modules — they give KSafe OS-backed key custody (Keychain / DPAPI / Secret Service), a core KSafe guarantee:
compose.desktop {
application {
nativeDistributions {
// jdk.unsupported → OS-backed key custody + DataStore. JNA and DataStore's
// protobuf both need sun.misc.Unsafe, which lives in jdk.unsupported and
// which jlink can't detect statically, so it's trimmed from release builds.
// java.management → only for a non-default KSafeSecurityPolicy (WarnOnly /
// Strict / custom debugger probe). Default IGNORE policy → omit.
modules("jdk.unsupported", "java.management")
}
}
}
Why: jlink builds a trimmed JRE with only the modules it can statically detect. Two
things KSafe needs sun.misc.Unsafe for aren't detectable — JNA (the OS keyvault) and
DataStore's embedded protobuf (its normal storage serializer).
Without the module (KSafe 2.1.1+) the app does NOT crash. KSafe detects the missing
Unsafe at construction and switches to a no-Unsafe software backend. Only the key
location changes — storage and encryption do not:
- Storage stays Jetpack
datastore-core(same atomic writes / coordinator / fsync), just a custom JSON serializer instead of the protobuf. - Encryption stays AES-GCM; new keys use the configured
KSafeAesKeySize(BITS_256by default,BITS_128when explicitly selected). - The AES key drops from the OS store to a local
0700file (FileKeyVault) — KSafe'sSOFTWAREtier, the same one used when no OS keyring is reachable.protectionInfo.effectiveLevelreportsSOFTWARE.
Risk of the software tier (so you can advise correctly): the key file (…ksafe-keys.json)
holds the raw AES key Base64-encoded in the clear; anyone who can read it plus the
ciphertext (…ksafe.json) can decrypt everything — the only barrier is the 0700 permission.
The real exposure is off-host / same-user (an unencrypted backup, a copied/synced home dir, a
stolen drive). That's why the module — which moves the key into the OS store — is recommended
for production.
Migration: when the module is added later, KSafe migrates the fallback data forward
automatically on first launch — re-encrypting each entry under a freshly minted OS-backed key
(the just-used fallback values win) and renaming the old files to *.migrated. Dev runs
(./gradlew run) use the full local JDK and are unaffected.
Why the fallback exists: before KSafe 2.1.1 a jlink'd image without jdk.unsupported failed
in one of two ways, depending on the DataStore build — the write path is encrypt (JNA) →
DataStore.write (protobuf), and both need sun.misc.Unsafe. A build that tolerated the
missing Unsafe dropped writes silently; one whose protobuf hard-requires it crashed on
the first read. 2.1.1's JSON fallback loads no protobuf, so neither happens — it degrades to
a software key tier instead of losing data.
Multi-app desktop / web isolation — appNamespace
Android/iOS keystores are sandboxed per-app. JVM Desktop OS secret stores are per-OS-user
(shared across processes); web IndexedDB is per-origin. Two apps using the same
fileName collide on the same key. Set:
val ksafe = KSafe(fileName = "userdata", config = KSafeConfig(appNamespace = "com.example.myapp"))
Production desktop apps should set it explicitly. An explicit appNamespace namespaces
both the key-store destination and the data file (a per-namespace subdirectory),
so keys and ciphertext always move together. When unset, the namespace is a stable
shared constant (since 2.1.2 it is never derived from the launcher/jar name — that
derivation changed on every versioned release and orphaned the keys), so two no-namespace
apps under the same OS user share a key namespace: that's exactly why production apps set
it. Can also be set without code: -Dksafe.appNamespace=… or env KSAFE_APP_NAMESPACE.
ANTI-patterns (common mistakes — DO NOT generate this code)
❌ Don't forward a non-reified T to ksafe.get / ksafe.put inside a generic wrapper —
it does not compile ("Cannot use 'T' as reified type parameter"). Use the KSerializer
overloads; see "Repository data source".
❌ Don't look for a KClass overload. There is none; pass a KSerializer.
❌ Don't use ksafe(value, encrypted = true). encrypted: Boolean is deprecated.
KSafe is encrypted by default: ksafe(value) encrypts, ksafe(value, mode = KSafeWriteMode.Plain) opts out. There is no default = named param — the default
value is the first positional argument.
❌ Don't pass a bare null default. ksafe.get("k", null) / var x by ksafe(null)
always return null (reified T collapses to Nothing?). Use get<String?>("k", null)
or a typed declaration.
❌ Don't wrap a delegate in MutableStateFlow. KSafe is already reactive — use
ksafe.asMutableStateFlow(default, scope) (writable) or ksafe.asStateFlow(default, scope) / ksafe.asFlow(default) (read-only).
❌ Don't call ksafe.getStateFlow(...) more than once for the same key. Each call runs
stateIn() and launches a fresh watcher coroutine in the scope, so an inline call, a call
in a loop, or one inside a @Composable leaks one watcher per call until that scope dies.
Assign it to a val once, or use by ksafe.asStateFlow(default, scope), which caches its
StateFlow on first read. getFlow is cold — calling it repeatedly is free.
❌ Don't runBlocking { ksafe.put(...) }. Use the delegate, putDirect for
fire-and-forget, or suspend put from a coroutine.
❌ Don't use KSafeProtection in KSafeWriteMode.Encrypted(...). That constructor
takes KSafeEncryptedProtection. KSafeProtection is the read-side detection enum.
❌ Don't call getOrCreateSecret / verifyBiometric / awaitCacheReady synchronously.
They're suspend.
❌ Don't roll your own BiometricPrompt / LAContext. Add :ksafe-biometrics and
call KSafeBiometrics.verifyBiometric(...).
❌ Don't ask for HARDWARE_ISOLATED by default. It is slower and hardware-dependent.
The default encrypted mode already has platform-backed durable custody: Android relaxed
DEFAULT uses a Keystore KEK plus wrapped DEK, while Apple DEFAULT uses Keychain custody.
Reserve HARDWARE_ISOLATED for master passphrases / identity keys that justify the stronger
per-entry route and its possible fallback.
❌ Don't pass Activity context on Android. Always applicationContext.
❌ Don't create two KSafe instances for the same fileName. Singletons via DI.
(Safe-but-wasteful on Android/iOS/macOS/JVM since 2.1.2; still diverges on web.)
❌ Don't name keys encrypted_* or __ksafe_*, and don't end a key with a __ksafe_…__
sentinel segment behind a . or : (__ksafe_master__, __ksafe_master_locked__,
__ksafe_strict__, __ksafe_gen__, __ksafe_nsdel__, __ksafe_swfb__) — reserved
namespaces (3.0.0+): every write/delete throws IllegalArgumentException at the call site
(reads still work). Name the key after the data, not the treatment — "token", not
"encrypted_token"; everything is encrypted by default anyway.
❌ Don't try to rotate a single key. rotateKeys() is whole-store — there is no per-key
overload. It's suspend; call it off the main thread for large stores, and trigger it
from ONE place per fileName.
❌ Don't access one fileName from two processes. KSafe currently wires a
single-process coordinator and process-local cache/write queue; give a widget/service
process its own fileName.
❌ Don't forget appNamespace on JVM Desktop / web if multiple apps share a fileName.
"Data isn't persisted" — debugging checklist
Sponsors
Details
- Marketplace
- ioannisa/KSafe
- Category
- Community