Store IPTV credentials in platform secure storage instead of app database

[dwizzle204]

Summary

IPTV provider credentials should be stored using platform secure storage rather than directly in the normal app database or local preference storage.

The app currently needs to persist playlist/provider credentials such as:

server URL
username
password

These values are sensitive because they can grant access to a user's IPTV provider account. They should be protected differently from normal playlist metadata such as display name, sort order, favorites, hidden categories, or cached guide data.

Proposed behavior

Store playlist metadata in the normal app database, but store secrets in platform secure storage:

App database
- playlist_id
- display_name
- server_url
- provider_type
- secret_ref

Secure storage
- secret_ref -> username/password

Recommended platform mappings:

• iOS: Keychain
• Android: Android Keystore-backed storage, such as EncryptedSharedPreferences or equivalent
• Flutter legacy app: security fixes only, or flutter_secure_storage if still supported

Why this matters

Storing IPTV credentials in a normal local database increases the chance that credentials are exposed through:

• device backups
• debug extraction
• local database inspection
• accidental support bundles
• future sync/export features
• compromised devices
• unrelated bugs that expose app database contents

Secure storage does not make credentials impossible to extract on a compromised device, but it is the standard platform pattern for app secrets and is a better default than storing passwords directly with normal application data.

Suggested implementation direction

Introduce a small credential-store abstraction per active platform.

Example shape:

CredentialStore
- saveCredential(playlistId, username, password)
- loadCredential(playlistId)
- deleteCredential(playlistId)

The database should only retain a stable reference, for example:

secret_ref = "playlist:<uuid>"

The provider clients should retrieve credentials through the credential store when making API or playback requests.

Migration approach

For existing users:

1. On app startup, detect playlists with plaintext credentials in the existing database.
2. Write those credentials to platform secure storage.
3. Update the playlist row with a secret_ref.
4. Remove or null the plaintext password fields from the app database.
5. Verify the migrated credential can be loaded successfully.
6. Avoid logging any credential values during migration.

Migration should be idempotent so it can safely resume if interrupted.

Acceptance criteria

• New playlist credentials are stored in platform secure storage.
• The normal app database no longer stores plaintext passwords for newly created playlists.
• Existing plaintext credentials are migrated safely.
• Deleting a playlist also deletes its secure-storage credential entry.
• Export/debug/logging paths do not include raw usernames or passwords.
• Unit tests or equivalent checks cover save, load, delete, and migration behavior.
• iOS and Android use equivalent credential-store interfaces to reduce platform drift.

Non-goals

This issue does not need to change IPTV provider behavior or playback URL construction.

Xtream-style providers may still require credentials in API or playback URLs at request time. The goal here is to avoid storing those credentials in the normal app database and to reduce accidental exposure at rest.

[bsogulcan]

Hi @dwizzle204, thanks for the detailed and well-structured report — this is a fair point and I agree with the direction.

Current state (confirmed):

You're right. On iOS (and the tvOS/macOS apps, which share the same architecture), username and password are currently stored as plaintext columns in the playlist table of the
GRDB/SQLite database under Application Support. The database is also not excluded from device backups, and there is no Keychain usage in the apps today.

A couple of mitigating notes for context:

• iOS sandbox + Data Protection already encrypts the database at rest while the device is locked, so the practical exposure is mainly backups, debug extraction, and future export
  features — exactly the vectors you listed.
• As you noted in the non-goals, the Xtream protocol itself requires credentials in plaintext query parameters at request time, so this change improves protection at rest only. Still
  worth doing as it's the standard platform pattern.

Planned approach:

1. A small dependency-free KeychainCredentialStore (SecItem API), keyed by playlist UUID, using kSecAttrAccessibleAfterFirstUnlock so background refresh/downloads keep working.
2. Credentials hydrated from the Keychain at playlist load time in the repository layer, so API clients and playback URL building stay unchanged. The database keeps only the playlist
   row; password columns are written empty for new playlists.
3. Idempotent startup migration: move existing plaintext credentials to the Keychain, then blank the database columns. No credential values logged.
4. Deleting a playlist deletes its Keychain entry. Since Keychain items survive app uninstall on iOS, orphaned entries will also be cleaned up on launch.
5. Same pattern applied to tvOS and macOS. One caveat: on tvOS, Apple documents that Keychain data may be purged under storage pressure, so the app will fall back to prompting for
   re-entry if a credential can't be loaded.

The legacy Flutter app is deprecated and won't receive this change.

I'll start with iOS and roll it out to the other platforms from there.