# 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](#gap-01-ui-error-feedback)
2. [UI: Loading States](#gap-02-ui-loading-states)
3. [Security: Database Passphrase Not Enforced](#gap-03-security-database-passphrase-not-enforced)
4. [Security: No Forward Secrecy Indicator](#gap-04-security-no-forward-secrecy-indicator)
5. [Documentation: Haskell Store Layer Not Fully Specified](#gap-05-documentation-haskell-store-layer-not-fully-specified)
6. [Desktop: Recording Not Implemented](#gap-06-desktop-recording-not-implemented)
7. [Desktop: Cryptor Not Implemented](#gap-07-desktop-cryptor-not-implemented)
8. [Desktop: App Link Registration](#gap-08-desktop-app-link-registration)
9. [Desktop: Emoji Picker Without Skin Tones and Localized Search](#gap-09-desktop-emoji-picker-without-skin-tones-and-localized-search)
10. [Badges: Limits on Moving a Badge to a New Device or Profile](#gap-10-badges-limits-on-moving-a-badge-to-a-new-device-or-profile)

---

## 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:

```kotlin
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.

```kotlin
// 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:

```kotlin
// 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.

---

## GAP-09: Desktop: Emoji Picker Without Skin Tones and Localized Search

**Severity:** Low
**Category:** Feature / Platform
**Platform:** Desktop only

### Description

The desktop compose emoji picker lists emoji without skin tone variants, and its search matches English Unicode emoji names only.

### Affected Locations

- `common/src/desktopMain/kotlin/chat/simplex/common/views/chat/ComposeEmojiPicker.desktop.kt`
- `scripts/desktop/generate-emoji-data.py` (`../../scripts/desktop/` relative to `apps/multiplatform/`) -- drops skin tone variants

### Impact

Desktop users cannot pick a skin tone in the picker, and search in other languages finds nothing.

### Recommendation

1. Keep the skin tone variants in the generated data, grouped by base emoji, and add a skin tone choice to the picker.
2. Add localized names (CLDR annotations) to the generated data for search.

---

## GAP-10: Badges: Limits on Moving a Badge to a New Device or Profile

**Severity:** Low
**Category:** Feature / Payments
**Platforms:** Android

### Description

Play gives a resubscription a new purchase token, so subscribing again on the same install is credited as a new purchase. On a new device or under another profile, Restore hands over the subscriptions in Play's list as restored, and the service moves the subscription to the restoring profile's purchase key. Restore is refused while the restoring profile shows a badge. A payment moves again only once the credential issued to the key it last moved from has expired; until then the move is refused `transfer_limited`. The first Restore's own answer doesn't say so: the app hears of the refusal only from core's purchase-refused event, which core sends only for a record holding an invoice id, and the next Restore is answered `transfer_limited` itself. A badge bought with Stripe or crypto cannot be moved at all. The app starts no plan change, and when tested Play's own pages offered none for these products; a plan change made there, should one become possible, would get a new token, which the app's sweep finds but core does not record, so only Restore claims it, and not under a profile that shows a badge, so the profile showing the old badge claims it only once that badge ends; until then it stays unacknowledged, which Play refunds after three days.

### Affected Locations

- `common/src/commonMain/kotlin/chat/simplex/common/views/badges/BadgeStore.kt` -- `restorePurchases()`
- `../../apps/simplex-badge-service/src/BadgeService/Service.hs` -- the move limit

### Impact

A subscriber who moves the badge again before the previous key's credential expires waits until it does, and the first such Restore may give no reason. A badge bought with Stripe or crypto stays with the profile it was credited to. Should Play offer a plan change for these products, a subscriber who makes one keeps the old badge until its paid months end, or until the service reads the old subscription ended at a month's check, and can lose the new plan to Play's refund before it is credited.

### Recommendation

1. Restore by a receipt code for Stripe and crypto purchases, shared with iOS.
2. Announce a limited move on the first Restore.
3. Before a Play plan change becomes possible, credit its new token without waiting for Restore.