simplex-chat/apps/multiplatform/product/gaps.md

Known Gaps & Recommendations -- SimpleX Chat (Android & Desktop, Kotlin Multiplatform)

This document catalogs known gaps in the multiplatform codebase (Android and Desktop) with severity, impact, and recommendations.

---

Table of Contents

1. UI: Error Feedback
2. UI: Loading States
3. Security: Database Passphrase Not Enforced
4. Security: No Forward Secrecy Indicator
5. Documentation: Haskell Store Layer Not Fully Specified
6. Desktop: Recording Not Implemented
7. Desktop: Cryptor Not Implemented
8. Desktop: App Link Registration

---

GAP-01: UI Error Feedback

Severity: Medium Category: UI / UX Platforms: Android, Desktop

Description

Many API calls through ChatController.sendCmd() return API.Error responses that are logged but not surfaced to the user. The general pattern is:

val r = sendCmd(rh, cmd)
if (r is API.Result && r.res is CR.ExpectedResponse) return r.res.value
Log.e(TAG, "someFunction bad response: ${r.responseType} ${r.details}")
return null

When the call fails, the caller receives null and either silently does nothing or shows a generic error. The specific ChatError details (which may contain actionable information like quota exceeded, server unreachable, or store errors) are lost to the user.

Affected Locations

• SimpleXAPI.kt -- getAgentSubsTotal(), getAgentServersSummary(), and dozens of similar api* functions
• Throughout the codebase wherever sendCmd results are pattern-matched

Impact

Users experience silent failures with no indication of what went wrong. This is particularly problematic for:

• Connection attempts that fail due to network issues
• File transfer failures
• Group operations that fail due to role permissions
• Server configuration errors

Recommendation

1. Introduce a structured error-handling utility that maps ChatError subtypes to user-visible messages, similar to how retryableNetworkErrorAlert already handles a subset of AgentErrorType.BROKER errors.
2. At minimum, surface a dismissible snackbar/toast with a summary when an API call fails unexpectedly.
3. For critical operations (send message, join group, create connection), show a dialog with retry/cancel options (the sendCmdWithRetry pattern already exists for some cases -- extend it).

---

GAP-02: UI Loading States

Severity: Low-Medium Category: UI / UX Platforms: Android, Desktop

Description

Several long-running operations lack loading indicators, leaving the user uncertain whether the action is in progress. The ComposeState.inProgress flag and progressByTimeout mechanism exist for the compose area, and ConnectProgressManager handles connection progress, but many other flows have no visual feedback.

Affected Locations

• Group member list loading (ChatModel.membersLoaded exists but is not always checked before displaying stale data)
• Server configuration validation (ApiValidateServers can take several seconds with no indicator)
• Database export/import (ApiExportArchive, ApiImportArchive)
• Profile switching (changeActiveUser_ acquires changingActiveUserMutex but the UI may appear frozen)

Impact

Users may tap actions multiple times, causing duplicate requests, or assume the app is frozen and force-quit during a long operation like database export.

Recommendation

1. Introduce a centralized ProgressOverlay composable that can be shown/hidden via a ChatModel flag.
2. Wrap all operations that acquire changingActiveUserMutex or take > 1 second with a visible loading state.
3. Use ChatModel.switchingUsersAndHosts (which already exists) more consistently as a gate for showing a blocking progress indicator.

---

GAP-03: Security: Database Passphrase Not Enforced

Severity: High Category: Security Platforms: Android, Desktop

Description

When the app is first installed, a random database passphrase is generated and stored in encrypted preferences. The user is never required to set a custom passphrase. The initialRandomDBPassphrase flag tracks this state, and a setup prompt exists in onboarding (SetupDatabasePassphrase), but the user can skip it.

On Android, the encrypted passphrase is stored via the Android Keystore, which provides hardware-backed security. On Desktop, the Cryptor is a placeholder (see GAP-07), meaning the passphrase is stored in plaintext.

Affected Locations

• SimpleXAPI.kt -- AppPreferences.storeDBPassphrase, AppPreferences.initialRandomDBPassphrase, AppPreferences.encryptedDBPassphrase
• common/src/commonMain/kotlin/chat/simplex/common/views/helpers/DatabaseUtils.kt
• common/src/commonMain/kotlin/chat/simplex/common/views/onboarding/SetupDatabasePassphrase.kt

Impact

• Users who skip passphrase setup rely entirely on device security. If the device is compromised, the database can be decrypted using the stored passphrase.
• On Desktop, the passphrase is effectively stored in plaintext (see GAP-07), meaning anyone with filesystem access can read the database.

Recommendation

1. Consider making passphrase setup mandatory during onboarding (or at least prominently warn users who skip it).
2. On Desktop, implement proper key storage (GAP-07) before any passphrase enforcement is meaningful.
3. Add a periodic reminder for users who still have initialRandomDBPassphrase == true.

---

GAP-04: Security: No Forward Secrecy Indicator

Severity: Medium Category: Security / UI Platforms: Android, Desktop

Description

The double-ratchet algorithm provides forward secrecy per message, and PQ key exchange provides resistance to quantum attacks. The Connection type tracks pqSupport, pqEncryption, pqSndEnabled, and pqRcvEnabled. However, the UI does not prominently display the current forward secrecy state or PQ encryption status for a given conversation.

Affected Locations

• ChatModel.kt -- Connection.pqSupport, Connection.pqEncryption, Connection.pqSndEnabled, Connection.pqRcvEnabled
• Contact info views, group member info views

Impact

Users cannot easily verify whether their conversations are using PQ-enhanced encryption. Security-conscious users have no visual indicator of the ratchet state or whether PQ key exchange was successful.

Recommendation

1. Add a security badge/icon in the chat header or contact info screen showing:
   • Whether PQ key exchange is active (both peers support it)
   • Whether the connection has been verified (security code comparison)
   • The ratchet state (in-sync vs. needs re-sync)
2. The connectionCode field on Connection can be used to show verification status.
3. The Call.encryptionStatus pattern (used in call views) could be adapted for the chat view.

---

GAP-05: Documentation: Haskell Store Layer Not Fully Specified

Severity: Medium Category: Documentation / Architecture Platforms: Android, Desktop

Description

The Kotlin client communicates with the Haskell core via a text-based command protocol (CC.cmdString -> FFI -> Haskell). The Haskell store layer (SQLite operations, migration logic, and the exact semantics of StoreError variants) is not documented from the Kotlin side. The ChatErrorStore error type wraps a StoreError whose variants are defined in Haskell and deserialized by the Kotlin client, but the conditions under which each error occurs are not specified.

Affected Locations

• SimpleXAPI.kt:6986 -- ChatErrorStore(storeError: StoreError)
• SimpleXAPI.kt -- StoreError sealed class (deserialized from Haskell responses)
• SimpleXAPI.kt -- ChatErrorDatabase(databaseError: DatabaseError) for migration errors

Impact

• Developers cannot predict which StoreError will occur for a given operation without reading the Haskell source.
• Error handling in the Kotlin layer is necessarily generic since the error semantics are not specified.
• Migration failures (ChatErrorDatabase) are particularly opaque.

Recommendation

1. Create a specification document mapping each CC command to its possible StoreError / DatabaseError responses.
2. Document the database migration versioning scheme and the conditions under which confirmDBUpgrades is triggered.
3. Add inline documentation to the StoreError sealed class variants explaining their trigger conditions.

---

GAP-06: Desktop: Recording Not Implemented

Severity: High Category: Feature / Platform Platform: Desktop only

Description

The RecorderNative class on Desktop is a placeholder. Both start() and stop() are stubbed with /*LALAL*/ comments and return dummy values (empty string and 0, respectively). Users cannot record voice messages on Desktop.

// common/src/desktopMain/kotlin/chat/simplex/common/platform/RecAndPlay.desktop.kt
actual class RecorderNative: RecorderInterface {
  override fun start(onProgressUpdate: (position: Int?, finished: Boolean) -> Unit): String {
    /*LALAL*/
    return ""
  }

  override fun stop(): Int {
    /*LALAL*/
    return 0
  }
}

Audio playback IS implemented on Desktop (via VLC/vlcj library), so received voice messages can be played. Only recording is missing.

Affected Locations

• common/src/desktopMain/kotlin/chat/simplex/common/platform/RecAndPlay.desktop.kt:15-25
• common/src/commonMain/kotlin/chat/simplex/common/platform/RecAndPlay.kt -- RecorderInterface

Impact

Desktop users cannot send voice messages. The record button either does nothing or produces a zero-length file.

Recommendation

1. Implement RecorderNative using a JVM audio capture library (e.g., javax.sound.sampled, or integrate with the existing vlcj dependency for capture).
2. The output format should match the mobile app's voice message format (likely Opus in an OGG container) for cross-platform compatibility.
3. Until implemented, the record button should be hidden or disabled on Desktop with a tooltip explaining the limitation.

Additional Desktop LALAL Placeholders

Several other Desktop features are also marked with LALAL placeholders:

• QR Code Scanner (QRCodeScanner.desktop.kt:12) -- scanning QR codes is not implemented on Desktop
• Animated Drawables (Utils.desktop.kt:236) -- getDrawableFromUri returns null, so isAnimImage falls back to the file extension
• isImage detection (Images.desktop.kt:189) -- image type detection (implemented but marked as incomplete)

Desktop cannot decode WebP in chat: decodeBoundedBufferedImage (Utils.desktop.kt:191) reads through ImageIO, which has no WebP reader, so a received .webp renders only as the sender's preview and never opens full screen, and a picked one is skipped. Wallpapers and link previews decode WebP, as they read through Skia instead (Images.desktop.kt:204). Received GIFs do animate in chat items and full screen; the animated image decoder accepts WebP but is never reached for it.

---

GAP-07: Desktop: Cryptor Not Implemented

Severity: Critical Category: Security / Platform Platform: Desktop only

Description

The CryptorInterface implementation on Desktop is a non-functional placeholder. All three methods are stubbed:

// common/src/desktopMain/kotlin/chat/simplex/common/platform/Cryptor.desktop.kt
actual val cryptor: CryptorInterface = object : CryptorInterface {
  override fun decryptData(data: ByteArray, iv: ByteArray, alias: String): String? {
    return String(data) // LALAL
  }

  override fun encryptText(text: String, alias: String): Pair<ByteArray, ByteArray> {
    return text.toByteArray() to text.toByteArray() // LALAL
  }

  override fun deleteKey(alias: String) {
    // LALAL
  }
}

• decryptData returns the data as-is (no decryption)
• encryptText returns the plaintext as both "encrypted data" and "IV"
• deleteKey is a no-op

Affected Locations

• common/src/desktopMain/kotlin/chat/simplex/common/platform/Cryptor.desktop.kt
• common/src/commonMain/kotlin/chat/simplex/common/platform/Cryptor.kt -- CryptorInterface
• common/src/commonMain/kotlin/chat/simplex/common/views/helpers/DatabaseUtils.kt -- uses cryptor for passphrase encryption

Impact

This is a critical security gap. On Desktop:

• The database passphrase is stored in plaintext in the preferences file. Anyone with read access to the user's home directory can extract the passphrase and decrypt the database.
• The self-destruct passphrase is similarly stored in plaintext.
• The app passphrase (for local authentication) provides no real protection.
• Key deletion is a no-op, so "deleting" a key has no effect.

This directly undermines RULE-02 (Database Encryption at Rest) and RULE-04 (Self-Destruct Profile) on the Desktop platform.

Recommendation

1. Priority: Critical. Implement proper key storage on Desktop using one of:
   • OS Keychain integration: macOS Keychain, Windows Credential Manager, Linux Secret Service (via libsecret/GNOME Keyring/KWallet)
   • Java Cryptography Architecture (JCA) with a PKCS#12 keystore file protected by a master password
   • Bouncy Castle library for platform-independent key management
2. Until a real implementation exists, display a prominent warning to Desktop users that their database passphrase is not securely stored.
3. Consider requiring the user to enter their passphrase on each app launch (do not store it) as an interim measure.

Related

• GAP-03 (Database Passphrase Not Enforced) is compounded by this gap on Desktop.
• The testCrypto() function referenced in AppCommon.desktop.kt:39 is commented out with a // LALAL marker, suggesting crypto testing was planned but never completed.

---

GAP-08: Desktop: App Link Registration

Severity: Low Category: Platform Platform: Desktop only

Description

Desktop registers the simplexchat: scheme so the badge page can return to the app, and the simplex: scheme so connection links open in it. The registration has known limits:

• Uninstalling or deleting the app leaves the per-user registration behind: the HKCU keys on Windows (the scheme keys, the ProgIds, Capabilities and the RegisteredApplications entry) and the hidden AppImage desktop entry on Linux. A later link then points at a missing program. On Windows, if the app was installed into a folder other users can write to (for example a custom folder at the root of C:\), another user could put a program at that path and have it run on the next link; the default Program Files install is not affected. This risk is accepted.
• A Flatpak counts as registered without a check, as it cannot query the host's default handler. It works only once the Flathub release pins a commit with the desktop file's MimeType line and its wrapper passes "$@" to the app.
• On macOS a second copy of the app does not forward a link to the running one; macOS delivers the link to the running bundle itself.
• With two installations (a deb and an AppImage, or two installed copies of the Windows app), the scheme stays with whichever registered first while it is installed; the other gets app=desktop. On Windows, when several apps registered through Capabilities handle a scheme and none was picked, Windows chooses or asks; the app cannot set UserChoice itself.
• The link arrives as a command-line argument, which other local users can read through /proc on Linux. This risk is accepted.

Affected Locations

• common/src/desktopMain/kotlin/chat/simplex/common/platform/AppLinkScheme.desktop.kt -- registration and its result for the badge page
• common/src/desktopMain/kotlin/chat/simplex/common/SingleInstance.kt -- forwarding to a running instance

Impact

A stale registration or an unregistered Flatpak sends the user back to a link that opens nothing; the badge page's Show code and the Redeem code screen remain.

Recommendation

1. Remove the registration in an uninstaller where one exists (MSI), and on AppImage when the entry's file is gone.
2. Removing the command-line exposure needs the page to encrypt the code to a key the app passes in the URL fragment.