Skip to content

feat!: Encly 3.0.0 on Kotlin Multiplatform for Android, desktop and iOS - #92

Open
pasichDev wants to merge 86 commits into
mainfrom
migrate-to-kmp
Open

pasichDev wants to merge 86 commits into
mainfrom
migrate-to-kmp

Conversation

@pasichDev

@pasichDev pasichDev commented Oct 29, 2026 •

Copy link
Copy Markdown
Owner

⏳ Draft: Encly 3.0.0: Android, desktop (Windows, macOS, Linux) and iOS on one Kotlin Multiplatform codebase. Android ships first; desktop and iOS follow.

Before merge: CI green on the head; a manual pass on a test device of the new editor, sheets, tasks and trash screens and the PIN screens.

After merge: switch the Weblate App component branch back to main; tag v3.0.0 (the first CI publish to Play, a 10 % staged rollout raised by hand in Play Console).

Before publishing desktop / iOS: signing secrets (desktopApp/README.md, "Signing the desktop installers"); a Windows install → upgrade → uninstall pass on a real machine; Apple Developer account, App Store Connect record, export-compliance answer (ITSAppUsesNonExemptEncryption) and a 1024 px icon with dark and tinted variants (iosApp/README.md).

What

Encly moves to Kotlin Multiplatform and ships as 3.0.0.

Modules

Module Targets Contents
:shared Android, desktop, iOS screens, ViewModels, navigation, design system, domain, data (backup, import, export); the iOS host
:editor Android, desktop, iOS the block editor library: public API, ABI dump, Dokka, 100 % line and branch coverage of its logic
:core:database Android, desktop, iOS Room + SecureDatabaseManager on the Sealite 1.0.1 driver (SQLCipher 4.20); schema 8
:core:security Android, desktop, iOS vault, PIN / duress / wipe / recovery slots, session lock, backups
:core:crypto Android, desktop, iOS one crypto API: JCA on the JVM, CommonCrypto and CryptoKit on iOS; own BIP-39; 100 % coverage
:core:keystore desktop, iOS PIN hardware factor: DPAPI, Keychain, Secret Service (encrypted session); Secure Enclave per guess on iOS
:core:common, :core:resources Android, desktop, iOS platform interfaces, wiping; strings of the ten languages
:app Android activities and Android adapters only
:desktopApp desktop windows, menu bar, PDF and print, installers (MSI, DMG, DEB, Flatpak)
iosApp/ iOS the SwiftUI shell around the shared framework

Replaced: sqlcipher-android → Sealite, Hilt → Metro, Gson → kotlinx.serialization, kotlin-bip39 → own encoding, java.time / UUID → kotlinx-datetime / kotlin.uuid, java.io / java.util.zip → kotlinx-io, R.string → Compose resources (translations stay in Android format for Weblate). Release APK 17.8 MB (2.3.x: about 29 MB).

New UI: sheets that move with the keyboard and hide on lock; the More sheet as tiles and a grouped note sheet; the tasks list by state (to do, in progress, done) with steps; the trash as a countdown to deletion; one button shape and a paired delete / save row; a back press can no longer pop two screens.

Issues closed by this release: #63 (Weblate), #83 (selection across blocks, block selection), #93 (settings in backups), #94 (screenshots until the app locks), #95 (PIN of 6–12 digits, keep the PIN after a recovery unlock), #97 (trash empties after 28 days), #98 (5 and 10 minute auto-lock), #103 (creation date), #104 (biometric unlock after a background lock), #105 (Arabic and RTL, hide previews, what's new), #108 (checklist lock remembered), #109 (several tags per note), and the open items of #76 (nested lists, drag to reorder, tables, code blocks, custom toolbar, checklist lock button). Desktop (#85, #106) and iOS (#107) are in the code and stay open until those builds ship. Includes #110 (a task or note never shows twice while its state changes; the "Key was already used" crash from Play).

From the release review:

  • Session lock: a screen already off or a keyguard already up when the app leaves the screen locks at once; on Android 14+ an alarm closes the vault of a frozen background process after the auto-lock delay; the decrypted note, a pending biometric enrolment and the hand-off payload are dropped on lock.
  • An unexpected startup failure opens the retry screen, not the wipe-only damaged-vault screen; a first-run restore killed half way starts onboarding over.
  • The clipboard is cleared only of Encly's own clip, also on lock and after the process was killed.
  • New fingerprints enrolled: the lock screen says so and hides the biometric button.
  • Trash: emptied in one transaction, a clock jump forward advances the purge by at most two days per unlock, notes with a hidden tag show as "Hidden note".
  • Editor: paste into lists, caret after Backspace and a committed link, a tap below the note continues it, table cell keys and accessibility, no autocorrect in code blocks.
  • Desktop: the Windows vault lives outside the install folder; a locked Linux keyring is named; macOS Quit goes through the orderly shutdown; a second start hands its files to the open window.
  • iOS: the keyboard no-learning hook works, privacy manifest, Face ID / Touch ID wording and invalidation, only reachable auto-lock delays.

Why

Desktop (#85, #54) and iOS need the logic and UI in common code, and Room's multiplatform API needs a driver sqlcipher-android does not provide. The issues above were reported by users of 2.3.x.

Behaviour changes

  • Vaults, recovery phrases, backups and notes from 2.3.x open unchanged (golden vectors, an upgrade test over a real 2.3.1 vault on an emulator with release builds).
  • Database schema 6 → 7 (trashedAt) → 8 (several tags per note); notes already in the trash start their 28 days with the update.
  • Backup payload schema 4 → 5 (optional settings); older apps answer "update the app" for a 3.0.0 backup.
  • The lock screen has an Unlock button: the PIN length is stored nowhere.
  • A note with a table or a code block opens read-only in versions before 3.0.0.
  • A backspace at the start of a list item joins it into the item above.
  • Editing a task no longer opens the keyboard by itself; editing a note keeps the description written for its card.
  • Play: 3.0.0 goes to production as a 10 % staged rollout.

Testing

CI runs fourteen jobs: unit and host tests of every module, Kover gates, detekt, ABI dumps, Dokka, R8 release builds and lint, instrumented tests on API 26 and 35 (Room migrations, a vault written by 2.3), iOS tests on the simulator (including the editor and database) and an unsigned xcodebuild, the desktop installers and a Flatpak bundle, the PIN factor against the real DPAPI, Keychain and Secret Service, and an F-Droid reproducibility check (two builds in different directories).

Manually:

  • Upgrade from 2.3.1 to the new build (release, minified, same signing key) on an emulator: PIN unlock, notes and archive intact, what's new shown, settings working.
  • Pixel 7a, debug build on a test vault: database 7 → 8 kept every tag, several tags per note work; frame times of a release-config build p95 7 ms, p99 29 ms.

Not verified: the release-review fixes on a device (the Android 14 frozen-process alarm, fingerprint re-enrolment, clipboard after a process kill); desktop installers on real Windows, macOS and Linux machines (install → upgrade → uninstall on Windows, Cmd+Q, KDE clipboard managers, Secret Service with KWallet/KeePassXC); iOS on a device (Secure Enclave, Face ID, keyboard, Backspace between blocks, clipboard).

References

#63, #76, #83, #85, #93, #94, #95, #97, #98, #103, #104, #105, #106, #107, #108, #109, #110

Room uses the androidx.sqlite driver API (SealiteDriver) instead of sqlcipher-android's open-helper factory. The key is the same raw DEK, so vaults written by earlier releases open unchanged; EarlierReleaseVaultTest writes one with sqlcipher-android 4.19 and opens it with the driver. Migrations, the trigger callback and backup transactions use SQLiteConnection.
… and UUID

Stored timestamps stay epoch milliseconds. Localized formatting (month names, field order, 12/24 h) stays in one platform function, LocalizedDate. The importer's date parser accepts the same inputs as before (ImportTimeTest pins 149 of them).
…stead of Gson

The stored JSON is unchanged byte for byte (BlockJsonFormatTest pins every block kind, Gson's HTML-safe escapes included), and reading stays as lenient as before.
Encly only turns 128 random bits into 12 words and checks phrases; it never derives a BIP-39 seed, so that part is not implemented. Bip39GoldenTest runs the official trezor vectors and pins the keys Encly derives from a phrase; Bip39WordlistTest pins the wordlist's SHA-256.
The archive readers, the Markdown export and the My Notes hand-off read and write kotlinx-io Sources and Sinks; java.util.zip stays behind small zip interfaces in one file (JvmZip). Every limit and check is kept: unsafe paths, entry count, entry and total sizes, zip bombs, CRCs, strict UTF-8. The Markdown export is pinned byte for byte.
AES-256-GCM, HKDF-SHA-256, PBKDF2, SHA-256 and the CSPRNG go through core/crypto/Crypto; JcaCrypto is the only file behind it that imports javax.crypto or java.security, so another platform replaces one file. Hygiene stays as before: a fresh Cipher and Mac per call, the PIN reaches PBKDF2 as characters and is cleared, HKDF wipes its PRK. CryptoGoldenTest pins every slot and the backup format, unchanged from the previous code.
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Coverage

Overall Project 83.82% -9.27% 🍏
Files changed 87.97% 🍏

File Coverage
HandlerMainThreadTimer.kt 100% 🍏
SharedPreferencesKeyValueStore.kt 100% 🍏
AppGraph.kt 100% 🍏
CacheHandoffStagingSweeper.kt 100% 🍏
AndroidDeviceCapabilities.kt 100% 🍏
SystemLockoutClock.kt 100% 🍏
ActivityBiometricHost.kt 100% 🍏
LocalDataModule.kt 100% 🍏
AndroidDocumentPickers.kt 99.08% -0.92% 🍏
AppLocales.kt 97.18% 🍏
AndroidHostServices.kt 96.57% -3.43% 🍏
MainActivity.kt 96.34% -0.3% 🍏
AndroidDocuments.kt 95.85% -4.15% 🍏
MyApplication.kt 94.12% 🍏
BiometricTexts.kt 90.8% -9.2% 🍏
KeystorePinFactor.kt 84.9% -15.1% 🍏
PendingDek.kt 82.08% -17.92% 🍏
AlarmMainThreadTimer.kt 80.98% -19.02% 🍏
SensitiveClip.kt 79.57% -20.43% 🍏
SecureTextInputBoundary.kt 78.68% 🍏
SystemDeviceLockWatcher.kt 77.78% -22.22% 🍏
ImportFromMyNotesActivity.kt 30.07% -22.42% 🍏

One compile-time AppGraph: singletons are @singlein(AppScope), the former modules are binding containers contributed to it, ViewModels are contributed into the Metro ViewModel factory (assisted for the three that take a SavedStateHandle), and the Activities inject themselves from the one graph in onCreate. Optional bindings are disabled, so a missing binding fails the build instead of falling back to a default. AppGraphTest checks that every security singleton is a single instance and that every ViewModel can be created.
Everything the editor needs from the app now comes through its own extension points (EditorStrings, EditorTheme, EditorClipboard, LinkOpener, EditorLogger, EditorController), so com.pasich.encly.editor imports nothing from the app; EditorBoundaryTest keeps it that way. The package is gated at 100% line and branch coverage. Backspace in an empty link address now removes the block from a hardware keyboard too (onPreviewKeyEvent, like the other fields). Stored note JSON is unchanged.
…layers

Domain, repositories, backup, import, export, hand-off and the security core no longer import android.* or java.*: SharedPreferences, the main-thread timer, biometrics, the Keystore PIN factor, device lock, app strings and the vault file I/O sit behind small interfaces with one Android implementation each. The vault slot file keeps its DataOutputStream format byte for byte (VaultStoreLegacyFormatTest) and its fsync and atomic replace (JvmVaultFileIo). PlatformBoundaryTest keeps the layers platform-free.
…ion plugins

build-logic holds the convention plugins (KMP library, Compose Multiplatform, quality, spotless). :editor targets Android, desktop JVM and iOS; its sources moved unchanged into commonMain, with one expect/actual for IDN hosts. It keeps 100% line and branch coverage, a checked ABI dump and Dokka docs; CI compiles the iOS targets on macOS.
:core:database holds the Room database, its entities, DAOs, migrations and SecureDatabaseManager for Android, desktop and iOS. The platform gives only the file location and the builder (DatabasePlatform); on Android the files stay where they are (database.db, vault_b.db). Desktop tests open, migrate and reject vaults encrypted with Sealite's JVM natives; the instrumented tests run from the module.
:core:common (platform interfaces, UiText, wiping), :core:crypto (the Crypto API with JCA behind it for Android and desktop, BIP-39) and :core:security (vault, PIN and recovery slots, session lock, backups). Locks move to atomicfu with the same critical sections (the same monitor bytecode on the JVM). Crypto and security have no iOS target yet: public CommonCrypto has no AES-GCM, and no weaker stand-in is shipped. :core:crypto is gated at 100 % line and branch coverage.
@pasichDev pasichDev self-assigned this Oct 29, 2026
:core:resources holds every string and plural of the nine languages. The translation files stay in Android format, byte for byte, so Weblate keeps working; a build step converts them into Compose resources (escapes, bare %d and %% included), and AndroidStringsConversionTest checks every string and plural against the Android values. The in-app language follows through the process locale. Biometric prompts get their texts as plain strings, loaded before the first prompt.
:core:keystore gives desktop the same PIN hardware factor contract as Android: HMAC-SHA256 over salt and PIN with a random 32-byte secret that lives only in the OS store of the user (DPAPI on Windows, the login Keychain on macOS, the Secret Service on Linux), one per key slot. A missing or unreadable secret behaves like a lost Keystore key. SECURITY.md describes the weaker, software-bound threat model. The keystore-it job runs the real backends on Windows, macOS and Linux.
…orm module

:shared holds the screens, ViewModels, navigation, design system, domain and platform-free data code for Android and desktop. :app keeps the activities and the Android adapters behind small platform interfaces (documents and pickers, links, toasts, sensitive clipboard, window security, biometric host, locale, app info). SharedBoundaryTest keeps Android and JVM APIs out of the common code. No test was dropped (1314 -> 1362).
@pasichDev pasichDev changed the title refactor: prepare Encly for Kotlin Multiplatform (Sealite driver, platform-free core) refactor: move Encly to Kotlin Multiplatform (shared UI and core modules, desktop key store) Oct 29, 2026
:desktopApp runs the shared UI in a Compose Desktop window with its own Metro graph: the vault in an owner-only app-data folder, the PIN factor in the OS secret store, native file dialogs (XDG portal on Linux), a native menu bar with shortcuts, drag and drop of backups and imports, remembered window state, a single instance per user. Security parity: capture exclusion where the OS allows it, lock on OS screen lock, minimise and idle, clipboard wiped after 60 s. Installers: MSI, DMG and DEB, built unsigned in CI.
Hand cursor and a keyboard-only focus ring on every interactive element, tooltips on hover as well as on long-press, context menus from a right click, the Menu key or Shift+F10 on notes, tasks and editor blocks (never from a finger), themed scrollbars on desktop, and app shortcuts with the platform's modifier (new note, find, lock, tabs, delete, Esc). Touch behaviour on Android is unchanged; the editor keeps 100 % coverage.
Compact windows keep today's phone UI exactly. Medium windows get a navigation rail and centred content; expanded windows a permanent drawer, the notes list beside the editor and tabs for open notes (#85). Sheets become centred dialogs on wide windows, and a tighter spacing set applies on pointer-first desktops. Relock clears every pane and tab before the lock screen shows, and reopens the active note as a tab after unlock.
The keyboard host at the app root and the menu bar share one key map and
one router, so every chord has a single owner. Note cards get a context
menu and a current-note highlight on pointer devices, tabs close on
middle-click and open in the background on Ctrl/Cmd+click, and the long
pages and lists show scrollbars. The database vault and the view model
factory move into the shared module, and the menu titles are translated.
The Linux packaging job also builds a Flatpak from the app image, with no
network access and only the bus names the key store and the lock watcher
use. The macOS DMG is signed, notarized and stapled and the Windows MSI is
signed only when their secrets exist and the run is not a pull request;
otherwise the installers stay unsigned as before.
note_tags (noteId, tagId) replaces notes.tagId in schema 8. Migration 7 -> 8
copies every note's tag into it, drops tags that point at no tag, and rebuilds
notes without the column, keeping its index, uid triggers and id counter.

Refs: #109
The backup payload goes to schema 6: a note lists its tags as tagUids. Files of
schema 1 to 5 are read with the note's one tag as the list. Importers keep all
of a note's tags instead of the first, Markdown front matter lists them all
(a quoted tag with a comma reads back whole), and the PDF names them.

Refs: #109
A tag's view lists every note with that tag, in one query. A note with any
hidden tag stays out of every list but a hidden tag's view. The list sheet puts
on or takes off one tag at a time, and the editor saves only the tags it
changed, so a tag changed elsewhere meanwhile stays. Tag counts come from one
query.

Refs: #109
The note sheet's tag chips and the editor's tag sheet toggle each tag and stay
open; No tag clears them. A card names the first two tags and counts the rest,
and the editor's overline shows every tag.

Refs: #109
- sheets slide with the keyboard in one motion and close with it
- one set of motion tokens; sheets slide away before a row's action runs
- editor more sheet: action tiles, text size and spacing with fixed resets
- note actions sheet as grouped rows with tags, colour and description pages
- tasks list grouped into in progress, next and done, with steps that open
  from a counter, inline add, rename and reorder over the keyboard
- trash sorted by days left before the 28-day purge, clear with a count
- buttons share the FAB corner radius; delete and save as an equal pair
- back pressed twice no longer leaves an empty window
- lock the vault at once when the screen is already off at stop, and
  wake a frozen background process with an alarm for the auto-lock delay
- route unexpected startup failures to the retry screen, not the wipe-only one
- drop a pending biometric enrolment, the hand-off payload and the open
  note's plaintext when the vault locks; tell the user when biometrics changed
- clear only Encly's own clip, also on lock and after process death
- restart onboarding when a restore was killed half way
- editor: paste into lists, caret after backspace and link commit, tap below
  the note, table semantics and keys, no autocorrect in code blocks
- ui: sheets hide on lock, no double back, live pin errors, tasks error state
- data: trash empties in one transaction and survives clock jumps, hidden
  notes stay hidden in the trash, card descriptions survive edits
- ci: staged 10% production rollout on play
- windows: keep the vault and its dpapi key outside the install folder
- linux: say when the keyring is locked, mark copied text as secret
- macos: quit through the normal shutdown, no jvm attach, owner-only exports
- desktop: second start hands its files to the open window, close window
  command, file extensions kept, wide-window tag picker as a dialog
- ios: keyboard no-learning fixed, no password mode on note fields, privacy
  manifest, face id wording and invalidation, clip wiped on lock, only
  reachable auto-lock delays, localized face id text, not offered on macs
- desktop and ios texts without android-only wording, own what's new
- run the ios editor and database tests in ci, refresh the public api dumps
The grip sat 4 dp below a block's top, so in a code block, a table or a
heading it stood above the first line. Each text field now gives the middle
of its first line as an alignment line, the topmost one in a block counts,
and the grip is centred on it; a block without text keeps the old place.
The APK carried only the libraries' profiles, so the app, editor and core
code ran interpreted after an install or an update until ART learnt it.
On a Pixel 7a the note open went from 5.7 % to about 4.7 % janky frames and
p90 from 20 to 15 ms, the same as a full AOT compile. F-Droid variants still
ship without ART profiles.
@pasichDev pasichDev mentioned this pull request Nov 17, 2026
Starting a new note from a template and leaving it without typing saved a
note holding only the template's headings, while an empty new note is not
saved. The editor now remembers the blocks a template made, and a new note
without a title whose blocks are still exactly those counts as blank, so Back,
autosave, the lock and process death all skip it. Any edit keeps it; an
existing note is never dropped.
- Hidden tags: the tag sheet says what hiding does (the notes leave the list
  and stay under the dimmed chip) instead of "no filter chip".
- The task list's add button says sub-task, as the rest of the app does.
- Note card previews read as text: ☐/☑ for checklist items, • for bullets and
  a short rule for a separator, not Markdown markers.
- The note sheet shows "No description" when there is none.
- With the keyboard open, the recovery phrase and word check forms drop the
  empty row and margin above it, so the fields stay in view above the button.
- A long task title wraps over up to four lines; Enter still moves on.
- The PIN check before an export draws under the system bars, with bar icons
  matching the app.
- Text buttons centre a wrapped label; Latin text in an RTL layout keeps its
  own direction in note cards and task rows.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant